ab_mcp — give an AI a folder, not your whole disk

I kept wanting to let Claude help with a project folder — "what's in here?", "find every TODO", "read me that config" — without giving it the keys to my entire filesystem. So I wrote this.

It's a tiny Model Context Protocol server: it hands an AI assistant a handful of file tools, all locked to one folder you choose. Reading is on by default; writing is off until you say otherwise. The whole thing is a single, readable server.py — so before you trust it, you can actually read it.

Why you might want this: "AI can read my files" and "AI can rewrite my files" are very different levels of trust. This server lets you start with the first and opt into the second only when you mean to.

What it can do

Tool	What it does
list_files(subdir=".")	List files/folders under the root
read_file(path)	Read a text file (size-capped)
read_lines(path, start=1, end=0)	Read a line range — for files too big to read whole
search_files(query, subdir=".", max_results=0)	Case-insensitive text search across files
find_files(pattern="*", subdir=".")	Find files by name/glob, e.g. *.py
file_stats(path=".")	Line/word/char counts, or directory size
write_file(path, content)	Create/overwrite a file — disabled unless AB_MCP_ALLOW_WRITE is set

Every path is confined to the root directory — requests that try to escape it (../../etc/passwd) are rejected.

Setup

cd ab_mcp
python -m venv .venv
source .venv/Scripts/activate      # Windows Git Bash
# .venv\Scripts\activate           # Windows PowerShell/cmd
pip install -r requirements.txt

Try it standalone (dev inspector)

mcp dev server.py

This opens the MCP Inspector in your browser so you can click each tool and see output.

Run it directly

python server.py

The server speaks stdio — it waits for an MCP client to connect. That's normal; it won't print anything on its own.

Configuration

Everything is controlled with environment variables — no code edits needed:

Variable	Default	Purpose
AB_MCP_NAME	ab_mcp	Server name advertised to MCP clients
AB_MCP_ROOT	this project folder	The single folder all tools are confined to
AB_MCP_MAX_BYTES	200000	Max file size (bytes) that read_file will read whole
AB_MCP_MAX_RESULTS	50	Default number of search hits before stopping
AB_MCP_LINE_PREVIEW	200	Characters of each matching line shown in search results
AB_MCP_ENCODING	utf-8	Text encoding used to read files
AB_MCP_ALLOW_WRITE	(off)	Set to 1/true/yes to enable the write_file tool
AB_MCP_IGNORE	.venv,venv,__pycache__,.git,node_modules,.idea	Comma-separated folders to skip

Example — point it at any folder, allow larger files, ignore a dist dir:

AB_MCP_ROOT="/path/to/your/folder" \
AB_MCP_MAX_BYTES=500000 \
AB_MCP_IGNORE=".git,dist,build" \
python server.py

Connect it to Claude Desktop

Edit claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows) and add:

Replace the paths with the absolute path to your own clone:

{
  "mcpServers": {
    "ab_mcp": {
      "command": "C:\\path\\to\\ab_mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\ab_mcp\\server.py"],
      "env": {
        "AB_MCP_ROOT": "C:\\path\\to\\the\\folder\\to\\expose"
      }
    }
  }
}

Restart Claude Desktop. You'll see the ab_mcp tools available in the chat.

Connect it to Claude Code

claude mcp add ab_mcp -- /path/to/ab_mcp/.venv/Scripts/python.exe /path/to/ab_mcp/server.py

License

MIT — see the LICENSE file. Add your name to the copyright line before publishing.