How to add codemcp to Windsurf

Turn Claude Desktop into a pair programmer that edits files, runs tests, and Git-versions every change. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 1.6k★ · stdio · no auth

Windsurf config for codemcp

uvx --from git+https://github.com/ezyang/codemcp@prod codemcp

{
  "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.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the codemcp config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5codemcp's tools become available to Cascade.

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

What codemcp can do in Windsurf

init_project

Initialize 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_file

Read 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_file

Write (overwrite) a file with new content, accompanied by a short description; the change is committed to Git.

edit_file

Apply a targeted edit to an existing file by replacing an old string with a new string using robust matching strategies; commits the change.

ls

List files and directories at a given absolute path.

glob

Fast file pattern matching across any codebase size using glob patterns like '**/*.ts'; returns matching paths sorted by modification time.

grep

Search file contents for a regular-expression pattern using git grep, with optional path and include-pattern filters.

run_command

Run a command predeclared in codemcp.toml (e.g. format, lint, test) with optional arguments; unrestricted shell is not allowed.

Security

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the codemcp config there under the "mcpServers" key and restart the client.

Is codemcp safe to use with Windsurf?

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.

View repo Full codemcp page