<p align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&color=0:4285F4,100:34A853&height=200&section=header&text=MCP File Manager&fontSize=60&fontColor=ffffff&animation=fadeIn" alt="banner" /> </p>

<p align="center"> <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"/> <img src="https://img.shields.io/badge/package%20manager-uv-de5fe9?logo=uv&logoColor=white" alt="uv"/> <img src="https://img.shields.io/badge/protocol-MCP-6E56CF" alt="MCP"/> <img src="https://img.shields.io/badge/LLM-Gemini%20API-4285F4?logo=googlegemini&logoColor=white" alt="Gemini API"/> <img src="https://img.shields.io/badge/license-MIT-informational" alt="MIT License"/> </p>

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

Requirements

• Python 3.10+
• uv for dependency management
• A free Gemini API key from Google AI Studio

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

• Model Context Protocol docs
• MCP Python SDK
• Gemini function calling

License

MIT License.