mcp-file-managerbeta

MCP File Manager

A local MCP client/server pair that gives an LLM safe, tool-mediated access to your filesystem, straight from the terminal.

PythonFastMCPMCP SDKGoogle Gemini API
0
MCP tools exposed
0
retries before graceful fallback
0
LLM-driven prompts
0
dynamic file resource

A terminal-native MCP client and server pair that lets Gemini read, write, and clean up files in any directory — no copy-pasting code into a browser chatbot.

01

The problem

Getting an LLM's help on a piece of code usually meant copying it out of my editor and pasting it into a browser tab, losing directory context and repeating the round trip for every file. I wanted Gemini to read, summarize, and clean up code directly from the filesystem I was already working in without leaving the terminal — and to do it over a protocol a client other than mine could reuse, instead of a one-off script wired straight to an API.
02

What I built

I built both sides of the exchange: an MCP server (FastMCP) exposing five filesystem tools — list_directory, read_file, write_file, delete_file, update_file — a file:// resource for attaching file contents, and two prompts (summarize_file, clean_up_code); and an MCP client that spawns the server as a subprocess over stdio, forwards its tool schema to Gemini as function declarations, and drives the resulting tool-call loop — executing whichever tool Gemini requests and feeding the result back until it returns a final answer. The part that took real engineering was resilience: Gemini calls sometimes fail outright and sometimes hang, so I split failures into retryable ServerErrors (exponential backoff, three attempts) versus terminal ClientErrors (fail fast), and made both fall back gracefully to the next prompt instead of taking the whole session down.

// how a request flows through mcp-file-manager
user
chat loop
MCP clientGemini function calling
Gemini APIfunction calling
MCP serverJSON-RPC over stdio
toolslist / read / write / delete / update
resourcesfile:// via @
promptssummarize / cleanup via /
zsh
$ python client.py
Connected to server. 5 tools available:
  - list_directory
  - read_file
  - write_file
  - delete_file
  - update_file
You: /summarize_file server.py
  [tool call] read_file({'path': 'server.py'})
  [tool result] import os\n\nfrom mcp.server.fastmcp import FastMCP...
Gemini: This file defines an MCP server exposing 5 filesystem tools,
1 file:// resource, and 2 prompts (summarize_file, clean_up_code).
# on a Gemini 503, retries 3x with backoff before falling back gracefully
client.py
# retry Gemini calls, but never crash the chat loop
async def _call_gemini(self, contents):
    for attempt in range(1, MAX_ATTEMPTS + 1):
        try:
            return self.genai_client.models.generate_content(...)
        except ServerError as e:
            if attempt == MAX_ATTEMPTS:
                return None  # give up, fall back to the prompt
            await asyncio.sleep(2 ** attempt)
        except ClientError as e:
            return None  # not retryable
03

Results & impact

◆

Classified Gemini API failures into retryable (ServerError, exponential backoff, 3 attempts) versus terminal (ClientError, fail fast) so an overloaded or slow model never crashes the chat session — it falls back to the next prompt instead.

◆

Exposes 5 filesystem tools, 1 dynamic file:// resource, and 2 LLM-driven prompts (summarize_file, clean_up_code) through the standard MCP tool-calling protocol, so any MCP-compatible client can drive it, not just this one.

◆

Replaced copy-pasting code into a browser chatbot with a single @filename mention that attaches the file as a resource directly in the terminal.

$ ./say-hello.sh

Let's talk about your backend.

Open to backend and platform engineering roles, and to interesting infrastructure problems. Fastest reply is by email.

© 2026 Elyas BromandBuilt with ♥ by Elyas Bromand↑ back to top