project-mcp

A small, read-only MCP server that lets Claude read the source code of your projects. You keep your projects in one folder; Claude can then read the current version of your files instead of relying on pasted snippets.

The simple mental model

1. There is a projects/ folder.
2. You create one sub-folder per project inside it.
3. Claude can read the code in those sub-folders. That's it.

project-mcp/
  project_mcp.toml        <- one line of config
  projects/               <- you create this
    some-project/         <- project

Drop a new folder into projects/ and it shows up automatically — no config change needed.

Setup

cd project-mcp
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

mkdir projects                     # your projects live here
cp project_mcp.example.toml project_mcp.toml

The default project_mcp.toml needs a single line:

projects_root = "projects"

A relative path is resolved next to the config file, so this means "the projects/ folder next to this config". Done.

MCP version note: this server pins mcp>=1.2,<2. The official SDK is now at 2.0, which removed the from mcp.server.fastmcp import FastMCP import that this server (and research-mcp) use. The pin keeps it working and consistent with research-mcp.

Connect it to Claude Desktop

Add an entry to claude_desktop_config.json. Using the venv's Python by absolute path is the most robust:

{
  "mcpServers": {
    "project-mcp": {
      "command": "/absolute/path/to/project-mcp/.venv/bin/python",
      "args": ["-m", "project_mcp"],
      "env": {
        "PROJECT_MCP_CONFIG": "/absolute/path/to/project-mcp/project_mcp.toml"
      }
    }
  }
}

(On Windows use ...\.venv\Scripts\python.exe.) Restart Claude Desktop; project-mcp then appears next to research-mcp in the tool list. A good first check: ask Claude to run list_projects.

Tools (all read-only)

Tool	Purpose
list_projects()	the projects Claude can see + how many readable files each has
list_files(project)	readable files in a project (exclusions already applied)
read_code(project, path, max_chars=100000)	read one file
search_code(query, project=None, max_results=50)	substring search across readable files

No writing, no deleting — for "review my code" reading is enough and much safer.

Security model

The config is the policy, and it is enforced in code — the server cannot read anything the policy forbids, regardless of what a request says. Two boundaries are checked, in order:

1. The named project must be visible (either auto-discovered under projects_root, or on the include_projects allow-list if you set one).
2. The file must resolve to a path inside that project (containment is checked after Path.resolve(), so .. segments and symlinks are collapsed first and then rejected), must not sit in an excluded directory, must have an allowed suffix, and must not match an excluded glob (e.g. .env, *secret*).

By default any folder you place in projects/ is readable. If you want tighter control — say you keep NDA/company code around — set include_projects to an explicit allow-list so a project is only visible when you name it on purpose. Either way, the secret-file exclusions (.env, *.key, *secret*, …) always apply.

Tests

pytest      # 13 tests, focused on path confinement:
            # .. escapes, symlink escape, allow-list, exclusions, suffixes,
            # and auto-discovery

Project structure

project-mcp/
  project_mcp.example.toml   config template
  pyproject.toml
  src/project_mcp/
    config.py    load config (projects_root, optional allow-list, exclusions)
    safe_io.py   security core: safe_resolve + read / list / search
    server.py    FastMCP server + the four tools
  tests/test_safe_io.py