Repository files navigation

Make Claude Desktop a pair programming assistant by installing codemcp. Withit, you can directly ask Claude to implement features, fix bugs and dorefactors on a codebase on your computer; Claude will directly edit files andrun tests. Say goodbye to copying code in and out of Claude's chat window!

codemcp offers similar functionality to other AI coding software (Claude Code,Cursor, Cline, Aider), but it occupies a unique point in the design space:

1. It's intended to be used withClaude Pro, Anthropic's $20/mosubscription offering. I like paying for my usage with a subscription planbecause it meanszero marginal cost for agent actions; no more feelingbad that you wasted five bucks on a changeset that doesn't work.

   Note that if you have Claude Max ($100/mo), Claude Code can also be usedwith subscription based pricing. The value proposition for codemcp ismurkier in this case (and it is definitely inferior to Claude Code in somerespects), but you can still use codemcp with Claude Max if you prefer someof the other UI decisions it makes. (Also, it's open source, so you canchange it if you don't like it, unlike Claude Code!)

2. It's built aroundauto-accept by default. I want my agent to get asfar as it can without my supervision, so I can review everything in one go atthe end. There are two key things that codemcp does differently than mostcoding agents: weforbid unrestricted shell, instead requiring you topredeclare commands the agent can use incodemcp.toml, and weGitversion all LLM edits, so you can roll back agent changes on afine-grained basis and don't have to worry about forgetting to commitchanges.

3. It'sIDE agnostic: you ask Claude to make changes, it makes them, andthen you can use your favorite IDE setup to review the changes and makefurther edits. I use vim as my daily driver editor, and coding environmentsthat require VSCode or a specific editor are a turn off for me.

To improve codemcp's token efficiency, on master I am in the process ofchanging codemcp back into a multi-tool tool (instead of a single tool whoseinstructions are blatted into chat when you InitProject). This means you haveto manually approve tool use. Because tool use approval is persistent acrossmultiple chats, I think this is a reasonable tradeoff to make, but if youreally don't like, file a bug atrefined-claude browserextension for supporting auto-approve tool use.

I recommend this specific way of installing and using codemcp:

1. Installuv and install git, if they are not installed already.

2. Installclaude-mcp on your browser.This enables you to connect to SSE MCP servers directly from the website,which means you don't need to use Claude Desktop and can easily havemultiple chat windows going in parallel. We expect this extension shouldbe soon obsoleted by the rollout ofIntegrations. At time ofwriting, however, Integrations have not yet arrived for Claude Pro subscribers.

3. Run codemcp usinguvx --from git+https://github.com/ezyang/codemcp@prod codemcp serve.You can add--port 1234 if you need it to listen on a non-standard port.

   Pro tip: if you like to live dangerously, you can changeprod tomain. Ifyou want to pin to a specific release, replace it with0.3.0 or similar.

   Pro tip: you can run codemcp remotely! If you useTailscale and trust all devices on your Tailnet,you can do this securely by passing--host 100.101.102.103 (replace theIP with the Tailscale IP address of your node. This IP typically lives inthe 100.64.0.0/10 range.)WARNING: Anyone with access to this MCP can performarbitrary code execution on your computer, it isEXTREMELY unlikely you want tobind to 0.0.0.0.

4. Configure claude-mcp with URL:http://127.0.0.1:8000/sse (replace the port if needed.)

5. Unfortunately, the web UI inconsistently displays the hammer icon. However, you can verifythat the MCP server is working by looking for "[MCP codemcp] SSE connection opened" in theConsole, or by asking Claude what tools it has available (it should saytools from codemcp are available.)

If you prefer to use Claude Desktop or have unusual needs, check outINSTALL.md forinstallation instructions for a variety of non-standard situations.

First, you must create acodemcp.toml file in the Git repository checkoutyou want to work on. If you want the agent to be able to do things like runyour formatter or run tests, add the commands to execute them in the commandssection (note: these commands need to appropriately setup any virtualenvironment they need):

format = ["./run_format.sh"]test = ["./run_test.sh"]

Theformat command is special; it is always run after every file edit.

Next, in Claude Desktop, we recommend creating a Project and putting this inthe Project Instructions:

Initialize codemcp with $PROJECT_DIR

Where$PROJECT_DIR is the path to the project you want to work on.

Then chat with Claude about what changes you want to make to the project.Every time codemcp makes a change to your code, it will generate a commit.

To see some sample transcripts using this tool, check out:

• Implement a new feature
• Fix failing tests
• Do a refactor

codemcp will generate a commit per chat and amend it as it is working on your feature.

• When you get rate limited, take the time to do something else (reviewClaude's code, review someone else's code, make plans, do some meetings)

• This isnot an autonomous agent. At minimum, you have to intervene afterevery chat to review the changes and request the next change. While youcan ask for a long list of things to be done in a single chat, you willlikely hit Claude Desktop's output limit and have to manually "continue" theagent anyway. Embrace it, and use the interruptions to make sure Claude isdoing the right thing.

• When Claude goes off the rails, it costs you time rather than dollars.Behave accordingly: if time is the bottleneck, watch Claude's incrementaloutput carefully.

Here are all the config options supported bycodemcp.toml:

project_prompt ="""Before beginning work on this feature, write a short haiku.  Do this only once."""[commands]format = ["./run_format.sh"]test = ["./run_test.sh"]

Theproject_prompt will be loaded when you initialize the project in chats.

Thecommands section allows you to configure commands for specific tools. Thenames are told to the LLM, who will decide when it wants to run them. You can addinstructions how to use tools in theproject_prompt; we also support a more verbosesyntax where you can give specific instructions on a tool-by-tool basis:

[commands.test]command = ["./run_test.sh"]doc = "Accepts a pytest-style test selector as an argument to run a specific test."

To run the server with inspector, use:

PYTHONPATH=. mcp dev codemcp/__main__.py

Logs are written to~/.codemcp/codemcp.log. The log level can be set in a global configuration file at~/.codemcprc:

[logger]verbosity ="INFO"# Can be DEBUG, INFO, WARNING, ERROR, or CRITICAL

Logging is not configurable on a per project basis, but this shouldn't mattermuch because it's difficult to use Claude Desktop in parallel on multipleprojects anyway.

SeeCONTRIBUTING.md.