codemcp

通过安装 codemcp，可以让 Claude Desktop 成为一个结对编程助手。使用它，你可以直接要求 Claude 在你的电脑上的代码库中实现功能、修复 bug 和进行重构；Claude 会直接编辑文件并运行测试。告别在 Claude 的聊天窗口中复制粘贴代码的日子吧！

codemcp 提供了与其他 AI 编码软件（如 Claude Code, Cursor, Cline, Aider）类似的功能，但在设计上有其独特之处：

1. 它旨在与 Anthropic 提供的每月 20 美元订阅服务 Claude Pro 一起使用。告别巨额 API 费用。（迎接基于时间的速率限制。）

2. 它围绕安全代理型 AI 构建，提供了一套有限的工具集，这些工具不太可能被乐于助人、诚实且无害的大语言模型滥用，并强制执行最佳实践，比如使用 Git 版本控制系统以确保所有代码更改都可以回滚。因此，你可以放心地释放 AI，并在最后决定是否接受更改。

3. 它是IDE 无关的：你让 Claude 进行修改，它完成修改后，你可以使用自己喜欢的 IDE 设置来审查这些修改并进一步编辑。

开始使用

首先，安装 uv 并 安装 git，如果尚未安装的话（对于 Windows 用户，如果你已经安装了 Git，建议重启计算机）。

然后，在 claude_desktop_config.json 文件中添加如下配置：

{
  "mcpServers": {
    "codemcp": {
      "command": "/Users/<username>/.local/bin/uvx",
      "args": [
        "--from",
        "git+https://github.com/ezyang/codemcp@prod",
        "codemcp"
      ]
    }
  }
}

在 Windows 上，路径中的双反斜杠是必需的：

C:\\Users\\<username>\\.local\\bin\\uvx.exe

修改 JSON 后，请重启 Claude Desktop 应用程序。如果 MCP 成功加载，将出现一个锤子图标，点击该图标时，“codemcp”将会显示。

使用 pip 全局安装

如果你不想使用 uv，也可以全局通过 pip 安装最新的 codemcp 版本，前提是你的全局 Python 安装足够新（Python 3.12），并且没有与 codemcp 冲突的 Python 依赖项。一些用户报告说这在 Windows 上更容易设置成功。

1. pip install git+https://github.com/ezyang/codemcp@prod
2. 向 claude_desktop_config.json 文件中添加以下配置：

{
    "mcpServers": {
         "codemcp": {
               "command": "python",
               "args": ["-m", "codemcp"]
            }
    }
}

1. 重启 Claude Desktop

你需要手动升级 codemcp 来获取更新，使用命令 pip install --upgrade git+https://github.com/ezyang/codemcp@prod

其他提示

专业提示：如果服务器未能加载，请前往 设置 > 开发者 > codemcp > 日志 查看 MCP 日志，这对调试非常有帮助。Windows 上的日志应该位于 C:\Users\<user_name>\AppData\Roaming\Claude\logs （请将 <user_name> 替换为你的用户名）。

专业提示：如果在 Windows 上日志显示“未找到 Git 可执行文件。请确保已安装 Git 并可用”，而你刚刚安装了 Git，请重启你的机器（PATH 更新尚未生效）。如果问题仍然存在，请打开系统属性 > 环境变量 > 系统变量 > 路径，并确保有一个针对 Git 的条目。

专业提示：如果你喜欢冒险，可以将 prod 更改为 main。如果你想固定到特定版本，可以将其替换为 0.3.0 或类似版本。

专业提示：只指定 uvx 作为命令是支持的，但 uvx 必须在你的全局 PATH 中（而不仅仅是通过 shell 配置文件添加）；在 OS X 上，如果你使用的是自安装程序（除非你安装到了系统位置如 /usr/local/bin），通常情况下不会这样。

使用方法

首先，你必须在想要工作的 Git 仓库检出中创建一个 codemcp.toml 文件。如果你想让代理能够执行一些操作，比如运行格式化工具或测试，请在命令部分添加执行它们的命令（注意：这些命令需要正确设置它们所需的任何虚拟环境）：

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

接下来，在 Claude 桌面版中，我们建议创建一个项目，并在项目说明中加入以下内容：

Initialize codemcp with $PROJECT_DIR

其中 $PROJECT_DIR 是你想工作的项目的路径。

然后与 Claude 聊天讨论你想对项目进行哪些更改。每次 codemcp 对你的代码做出更改时，它都会生成一个提交。

要查看使用此工具的一些示例记录，请参阅：

• 实现新功能
• 修复失败的测试
• 重构代码

codemcp 将会为每次聊天生成一个提交，并随着工作进展更新该提交。

哲学理念

• 当你遇到速率限制时，花点时间做些别的事情（审查 Claude 的代码、审查别人的代码、制定计划、参加一些会议）

• 这不是一个自主代理。至少，你需要在每次聊天后介入以审查更改并请求下一次更改。虽然你可以要求在单次聊天中完成很长的任务列表，但你可能会达到 Claude 桌面版的输出限制，最终仍需手动“继续”代理的工作。接受这一点，并利用中断来确保 Claude 正确行事。

• 当 Claude 出现偏差时，这会消耗你的时间而不是金钱。相应地行动：如果时间是瓶颈，仔细监控 Claude 的增量输出。

配置

以下是 codemcp.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"]

当你在聊天中初始化项目时，将加载 project_prompt。

commands 部分允许你为特定工具配置命令。这些名称会被告知给 LLM，LLM 将决定何时运行它们。你可以在 project_prompt 中添加如何使用工具的说明；我们也支持更详细的语法，允许你针对每个工具提供具体指令：

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

故障排除

要使用检查器运行服务器，请使用：

PYTHONPATH=. mcp dev codemcp/__main__.py

日志被写入 ~/.codemcp/codemcp.log。日志级别可以在全局配置文件 ~/.codemcprc 中设置：

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

日志记录不能按项目单独配置，但这不应该造成太大问题，因为无论如何都很难在多个项目中并行使用 Claude Desktop。

贡献

参见 CONTRIBUTING.md。

类型检查

此项目使用 pyright 进行类型检查，并启用了严格模式。类型检查的配置位于 pyproject.toml 文件中。我们采用了几种策略来维护类型安全：

1. 外部库的类型存根：

   • 自定义类型存根位于 stubs/ 目录下
   • pyproject.toml 中的 stubPackages 配置将库映射到它们的存根包

2. 针对复杂情况的文件特定忽略：

   • 对于一些具有复杂动态类型模式的文件（特别是测试代码），我们通过 pyproject.toml 中的 tool.pyright.ignoreExtraErrors 使用文件特定的忽略
   • 与内联忽略相比，这种方式更优，可以让我们在大部分代码库中保持类型安全

在进行修改时，请确保类型检查通过运行以下命令：

./run_typecheck.sh