codemcp
Turn Claude Desktop into a pair programmer that edits files, runs tests, and Git-versions every change.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uvx --from git+https://github.com/ezyang/codemcp@prod codemcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"codemcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ezyang/codemcp@prod",
"codemcp"
]
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.12+
- uv / uvx (recommended) or pip
- git installed and on PATH
- A Git-initialized project with a codemcp.toml file
- Claude Desktop (stdio), or Claude.ai with the claude-mcp browser extension for the SSE transport
About codemcp
codemcp connects Claude Desktop (or Claude.ai through the claude-mcp SSE browser extension) to a local Git repository so Claude can act as a hands-on coding agent: reading and editing files, searching the codebase, and running predeclared commands like formatters and test suites. Every change Claude makes is committed to Git (one commit per chat, amended as work proceeds), giving fine-grained rollback. Unrestricted shell is intentionally disallowed — the agent may only run commands you list in the project's codemcp.toml. It is designed to be used with a Claude Pro/Max subscription for zero marginal per-action cost.
Tools & capabilities (12)
init_projectInitialize codemcp for a project directory; reads codemcp.toml, loads the project_prompt and declared commands, and starts a chat/commit session. Triggered by asking Claude to 'Initialize codemcp with <project dir>'.
read_fileRead a file from the local filesystem given an absolute path; reads up to 1000 lines by default with optional offset/limit, and can display image files.
write_fileWrite (overwrite) a file with new content, accompanied by a short description; the change is committed to Git.
edit_fileApply a targeted edit to an existing file by replacing an old string with a new string using robust matching strategies; commits the change.
lsList files and directories at a given absolute path.
globFast file pattern matching across any codebase size using glob patterns like '**/*.ts'; returns matching paths sorted by modification time.
grepSearch file contents for a regular-expression pattern using git grep, with optional path and include-pattern filters.
run_commandRun a command predeclared in codemcp.toml (e.g. format, lint, test) with optional arguments; unrestricted shell is not allowed.
mvMove/rename a tracked file using git mv and commit the change, with a short description.
rmRemove a tracked file using git rm and commit the change, with a short description of why.
chmodAdd or remove the executable bit on a file (only a+x and a-x are supported, since those are the only permission bits Git tracks).
thinkAppend a reasoning thought to the log without changing files or fetching new information; used for complex reasoning or scratch memory.
When to use it
- Implement a new feature in a local codebase by chatting with Claude and letting it edit files and run tests
- Fix failing tests, with Claude iterating and running the predeclared test command until they pass
- Perform multi-file refactors while keeping every change as a reviewable Git commit
- Use Claude as a coding agent on a Claude Pro/Max subscription with zero marginal per-action cost
- Drive coding from Claude.ai in the browser (via the SSE bridge) so you can run several parallel chat windows
Security notes
Auto-accept by default: codemcp edits files and runs predeclared commands without per-action confirmation. To mitigate risk it forbids unrestricted shell (only commands listed in codemcp.toml can run) and Git-versions every edit so changes can be rolled back. If you run it as an SSE server reachable over the network, anyone with access to the MCP endpoint can achieve arbitrary code execution on your machine — bind only to localhost or a trusted Tailscale IP, never 0.0.0.0.
codemcp FAQ
Do I need a paid API key?
No. codemcp itself uses no API key and is designed to run on a Claude Pro ($20/mo) or Claude Max subscription, so there's no per-action marginal cost.
How do I stop the agent from running arbitrary shell commands?
codemcp forbids unrestricted shell by design. The only commands it can run are the ones you explicitly declare in the [commands] section of your project's codemcp.toml (e.g. format, lint, test).
Can I undo what the agent changed?
Yes. Every edit codemcp makes is committed to Git (one commit per chat, amended as it works), so you can roll back agent changes on a fine-grained basis without fear of losing your own uncommitted work.
How do I start working on a project?
Create a codemcp.toml in the Git repository you want to work on, then tell Claude 'Initialize codemcp with <path to project>' (often placed in a Claude Project's instructions), and chat about the changes you want.
Can I use it from the Claude.ai website instead of Claude Desktop?
Yes. Install the claude-mcp browser extension, run 'uvx --from git+https://github.com/ezyang/codemcp@prod codemcp serve', and point the extension at the SSE URL (default http://127.0.0.1:8000/sse). Only expose it on localhost or a trusted Tailscale IP — never 0.0.0.0.
Is codemcp still maintained?
The author now considers codemcp obsolete because Claude Code is available with Anthropic's subscriptions, but it is open-source (Apache-2.0) and remains usable, and some of its design ideas (like Git-versioned edits) are being ported forward.
Alternatives to codemcp
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
Code intelligence engine that indexes repos into a persistent knowledge graph for AI coding agents.
Compare codemcp with: