Skip to main content
Glama
mcp-file-manager

mcp-file-manager

by elyasbromand

MCP File Manager

A local Model Context Protocol (MCP) project that lets you manage files on your machine through natural language, powered by the Gemini API (free tier) as the client-side LLM.

The project has two halves that talk to each other over stdio (standard input/output pipes) — no network involved:

  • server.py — an MCP server exposing file-manipulation tools, read-only resources, and reusable prompts.

  • client.py — a terminal chat client that launches the server as a subprocess, connects to Gemini, and bridges the two: Gemini decides what to do, the server does it.

flowchart LR
    U([User]) -->|types message| C[MCP Client<br/>chat loop]
    C -->|conversation + tool schema| G[(Gemini API<br/>function calling)]
    G -->|final text| C
    G -.->|requests a tool call| C
    C <-->|JSON-RPC over stdio| S[MCP Server]
    S --- T[Tools<br/>list_directory, read_file,<br/>write_file, delete_file, update_file]
    S --- R[Resources<br/>file:// attachments via @]
    S --- P[Prompts<br/>summarize_file, clean_up_code via /]

    style G fill:#4285F4,color:#fff
    style S fill:#34A853,color:#fff
    style C fill:#111,color:#fff

Features

  • Tools (model-controlled — Gemini decides when to call these):

    • list_directory — list files/folders in a given path

    • read_file — read a file's contents

    • write_file — create or overwrite a file

    • delete_file — delete a file

    • update_file — find-and-replace text inside a file (supports replacing all occurrences or just the first)

  • Resources (user-controlled — attach a file to the conversation with @):

    • file:///{path} — exposes any file's content for direct attachment, no LLM tool call needed

  • Prompts (user-controlled — reusable instruction templates with /):

    • summarize_file — summarize a file's contents

    • clean_up_code — review and clean up a code file

  • Interactive chat client:

    • Type / alone to see a numbered picker of available prompts

    • Type @ alone to see a numbered picker of files in the current directory to attach

    • Or use them inline: /summarize_file report.txt, tell me about @report.txt

    • Full multi-step tool-calling loop — Gemini can chain multiple tool calls per turn

Related MCP server: File Operations MCP Server

Requirements

Setup

git clone <your-repo-url>
cd mcp_project

uv venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

uv sync

Create a .env file in the project root (never commit this file — it's already covered by .gitignore):

GEMINI_API_KEY=add-your-api-key

Usage

Run the client

uv run client.py

You'll see the list of tools the server exposes, then a You: prompt. Try:

You: list files in the current directory
You: create a file called notes.txt with the content "hello world"
You: change hello to goodbye in notes.txt
You: /
  1. /summarize_file - Ask the assistant to summarize the contents of a file.
  2. /clean_up_code - Ask the assistant to review and clean up a code file.
Pick a number: 1
  path: notes.txt
You: @
  1. notes.txt
  2. server.py
Pick a number: 1
Your message about this file: what's in here?

Type quit or exit to end the session.

Inspect the server directly (debugging)

The MCP Python SDK ships a visual inspector for testing tools/resources/prompts without involving an LLM at all:

uv run mcp dev server.py

Minimal Project structure

mcp-file-manager/
├── .env                # your Gemini API key (not committed)
├── pyproject.toml       # uv-managed dependencies
├── server.py            # MCP server: tools, resources, prompts
├── client.py            # MCP client: chat loop + Gemini integration
└── README.md

How it works (short version)

  1. client.py launches server.py as a subprocess and opens an MCP session over stdio.

  2. On startup, the client fetches the server's tool list and converts it into Gemini's function-calling schema.

  3. On each user message, the client sends the conversation + tool list to Gemini.

  4. If Gemini responds with a function call, the client executes it against the MCP server and feeds the result back to Gemini — repeating until Gemini returns a final text answer.

  5. / and @ are handled entirely on the client side (never sent to Gemini as-is) — they fetch a prompt or resource directly from the MCP server and inject the result into the conversation before the normal flow above runs.

Notes & limitations

  • This is a local, single-user learning project — the file tools operate with the same permissions as whatever account runs client.py, so be mindful of what directory you run it from.

  • update_file's find-and-replace is a plain read-modify-write; it isn't safe against concurrent edits to the same file.

  • The / command only supports single-argument prompts out of the box; extend _handle_prompt if you add multi-argument prompts.

Learn more

License

MIT License.

Available Tools

5 tools
delete_fileB

Delete the file at the given path.

Inputs: path (required). Returns: result

list_directoryA

List all files and folders in the given directory path.

Inputs: path. Returns: result

read_fileA

Read and return the full text content of a file at the given path.

Inputs: path (required). Returns: result

update_fileA

Find and replace text inside a file.

Use this when the user asks to change, replace, or update specific text within an existing file (e.g. "change X to Y in report.txt").

Args: path: Path to the file to modify. old_text: The exact existing text to search for. new_text: The text to replace it with. replace_all: If True (default), replace every occurrence. If False, replace only the first occurrence.

Inputs: path (required), new_text (required), old_text (required), replace_all. Returns: result

write_fileA

Create a file (or overwrite it if it exists) with the given text content.

Inputs: path (required), content (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a distinct purpose: listing, reading, writing, deleting, and updating files. The update_file tool's find/replace behavior is clearly differentiated from write_file's full-content overwrite, so there is no ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: list_directory, read_file, write_file, delete_file, update_file. This makes the API predictable and easy to navigate.

    Tool Count5/5

    With 5 tools, the server is well-scoped for a file manager. Each tool covers a core file operation without unnecessary redundancy or bloat.

    Completeness3/5

    The set covers file content CRUD (create, read, update, delete) and directory listing, but lacks directory management operations such as create/delete directory and rename/move. This leaves notable gaps for a full file manager, though the core file operations are solid.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers