mcp-file-manager
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-file-manager list files in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:#fffFeatures
Tools (model-controlled — Gemini decides when to call these):
list_directory— list files/folders in a given pathread_file— read a file's contentswrite_file— create or overwrite a filedelete_file— delete a fileupdate_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 contentsclean_up_code— review and clean up a code file
Interactive chat client:
Type
/alone to see a numbered picker of available promptsType
@alone to see a numbered picker of files in the current directory to attachOr use them inline:
/summarize_file report.txt,tell me about @report.txtFull multi-step tool-calling loop — Gemini can chain multiple tool calls per turn
Related MCP server: File Operations MCP Server
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 syncCreate a .env file in the project root (never commit this file — it's already covered by .gitignore):
GEMINI_API_KEY=add-your-api-keyUsage
Run the client
uv run client.pyYou'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.pyMinimal 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.mdHow it works (short version)
client.pylaunchesserver.pyas a subprocess and opens an MCP session over stdio.On startup, the client fetches the server's tool list and converts it into Gemini's function-calling schema.
On each user message, the client sends the conversation + tool list to Gemini.
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.
/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_promptif you add multi-argument prompts.
Learn more
License
MIT License.
Available Tools
5 toolsdelete_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
Scored across 5 tools
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.
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.
With 5 tools, the server is well-scoped for a file manager. Each tool covers a core file operation without unnecessary redundancy or bloat.
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
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables agents to manage and organize local documents by listing, inspecting, extracting text, searching, and renaming files, with optional Google Drive integration.-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to safely interact with the file system through a set of tools for reading, writing, deleting, copying, moving files, and managing directories.-
- FlicenseNot gradedqualityDmaintenanceEnables file operations, text processing, math utilities, and directory management through natural language for local development.-
- AlicenseAqualityDmaintenanceEnables AI clients to manage and manipulate text files in a secured local directory through tools like list, read, write, delete, create directory, and move.7MIT