Claude Code MCP Server：开源AI助手配置与使用完全指南

【免费下载链接】claude-code-mcp Claude Code as one-shot MCP server to have an agent in your agent. 项目地址: https://gitcode.com/gh_mirrors/claud/claude-code-mcp

Claude Code MCP Server 是一个创新的开源项目，它将 Claude Code 作为一次性 MCP 服务器运行，让你能够在现有的 AI 代理中嵌入更强大的代码处理能力。这个项目解决了 Cursor、Windsurf 等 AI 开发工具在处理复杂多步骤编辑时的局限性，通过统一的 claude_code 工具提供更直接、更高效的代码操作体验。

项目概述与价值定位 🎯

你是否遇到过 Cursor 在处理复杂文件操作时力不从心的情况？Claude Code MCP Server 正是为解决这个问题而生。它作为一个 MCP（模型上下文协议）服务器，让 Claude Code 能够以一次性模式运行，默认绕过权限检查，同时支持可选的本地 Claude Code 权限模式。

核心价值亮点：

• 突破工具限制：当 Cursor/Windsurf 在文件编辑上遇到困难时，Claude Code 通常更快更好
• 成本优化：文件操作、Git 管理等任务不需要昂贵的模型，Claude Code 在 Antropic Max 模式下成本效益更高
• 系统访问更广：Claude 拥有更广泛的系统访问权限，能够执行 Cursor/Windsurf 无法完成的操作
• 上下文管理：多个命令可以排队执行，节省上下文空间，减少压缩发生

环境准备与依赖检查 🔧

系统要求

• Node.js v20 或更高版本（推荐使用 fnm 或 nvm 安装）
• Claude CLI 已本地安装（运行 claude 并调用 /doctor 验证）

快速安装步骤

方法一：使用 npx（推荐）

{
  "claude-code-mcp": {
    "command": "npx",
    "args": ["-y", "@steipete/claude-code-mcp@latest"]
  }
}

方法二：全局安装

npm install -g @steipete/claude-code-mcp

重要首次设置：权限接受

在 MCP 服务器能够使用默认的 bypassPermissions 模式之前，你必须手动运行 Claude CLI 一次并接受条款：

claude --dangerously-skip-permissions

注意事项：

• 这是一个一次性要求，由 Claude CLI 强制执行
• macOS 可能在第一次运行时请求各种文件夹权限，首次运行可能会失败，后续运行将正常工作
• 确保按照提示完成所有接受步骤

核心配置文件解析 ⚙️

MCP 配置文件位置

根据你使用的客户端，配置文件的位置有所不同：

客户端	配置文件路径	平台支持
Cursor	~/.cursor/mcp.json	macOS/Linux/Windows
Windsurf	~/.codeium/windsurf/mcp_config.json	macOS/Linux/Windows

环境变量配置

变量名	描述	默认值
CLAUDE_CLI_NAME	覆盖 Claude CLI 二进制名称或提供绝对路径	claude
MCP_CLAUDE_DEBUG	启用调试日志记录	false
CLAUDE_CLI_TIMEOUT_SECONDS	覆盖 Claude CLI 执行超时时间（秒）	3600

CLAUDE_CLI_NAME 支持格式：

• 简单名称：claude-custom 或 claude-v2
• 绝对路径：/path/to/custom/claude
• 不支持相对路径（如 ./claude 或 ../claude）

自定义 Claude CLI 配置示例

{
  "claude-code-mcp": {
    "command": "npx",
    "args": ["-y", "@steipete/claude-code-mcp@latest"],
    "env": {
      "CLAUDE_CLI_NAME": "claude-custom"
    }
  }
}

启动流程详细说明 🚀

连接 MCP 客户端

配置好服务器后，需要配置 MCP 客户端。创建或更新配置文件，添加 claude_code 配置：

Cursor 配置示例：

{
  "mcpServers": {
    "claude_code": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@steipete/claude-code-mcp@latest"]
    }
  }
}

Windsurf 配置示例：

{
  "claude_code": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@steipete/claude-code-mcp@latest"]
  }
}

提供的工具

服务器暴露一个主要工具：claude_code

工具参数说明：

参数名	类型	必填	描述
prompt	string	是	发送给 Claude Code 的提示
workFolder	string	否	文件操作的绝对工作目录
sessionId	string	否	父会话 ID，相同 ID 的重复调用会恢复同一 Claude Code 会话
messages	array	否	首次调用会话时要注入的对话历史
stateless	boolean	否	为此调用禁用会话连续性
permissionMode	string	否	Claude Code 权限模式，默认为 bypassPermissions

权限模式选项：

• bypassPermissions：默认，绕过权限检查
• default：使用 Claude Code 的默认权限检查
• acceptEdits：接受编辑权限模式
• auto：自动权限模式
• dontAsk：不询问权限模式
• plan：计划权限模式

MCP 请求示例

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "重构 main.py 中的 foo 函数为异步函数",
    "workFolder": "/Users/username/my_project",
    "permissionMode": "default"
  }
}

常见问题排查指南 🔍

安装与启动问题

问题：出现 "Command not found" 错误

• 如果全局安装，确保 npm 全局 bin 目录在系统 PATH 中
• 如果使用 npx，确保 npx 本身正常工作
• 确保 Claude CLI 正确安装，运行 claude/doctor 或检查其文档

问题：权限相关问题

• 确保已完成"重要首次设置"步骤
• 如果父 MCP 客户端在等待自己的批准流程，请配置该客户端的 MCP 权限
• 或者使用 Claude Code 的原生 claude mcp serve 路径

问题：服务器返回 JSON 错误

• 如果 MCP_CLAUDE_DEBUG 设置为 true，错误消息或日志可能会干扰 MCP 的 JSON 解析
• 正常操作时设置为 false

问题：ESM/Import 错误

• 确保使用 Node.js v20 或更高版本

配置验证清单

1. ✅ Claude CLI 已安装并可执行
2. ✅ 已运行 claude --dangerously-skip-permissions 并接受条款
3. ✅ MCP 配置文件路径正确
4. ✅ 配置文件语法正确（JSON 格式）
5. ✅ 环境变量设置正确（如需要）
6. ✅ Node.js 版本符合要求（v20+）

进阶使用技巧分享 🚀

关键使用场景

1. 代码生成、分析与重构

{
  "prompt": "分析 my_script.py 中的潜在 bug 并提出改进建议"
}

2. 文件系统操作

• 创建文件：指定工作目录和文件内容
• 编辑文件：提供具体修改指令
• 移动/复制/删除：明确源路径和目标路径

3. 版本控制（Git）

{
  "prompt": "工作目录：/Users/username/my_project\n\n1. 暂存文件 'src/main.java'\n2. 提交更改，消息为 'feat: 实现用户认证'\n3. 推送到 origin 的 'develop' 分支"
}

4. 运行终端命令

{
  "prompt": "工作目录：/Users/username/my_project/frontend\n\n运行命令 'npm run build'"
}

5. 复杂多步骤工作流 自动化版本更新、更新变更日志和标签发布等复杂任务

性能优化建议

会话管理技巧：

• 使用 sessionId 参数维护会话连续性
• 对于独立操作使用 stateless: true
• 合理设置 CLAUDE_CLI_TIMEOUT_SECONDS 避免超时

成本控制策略：

• 将文件操作、Git 管理等任务委托给 Claude Code
• 在 Antropic Max 模式下使用更便宜的模型处理简单任务
• 利用排队执行减少上下文压缩

本地开发与贡献

如果你想要开发或贡献这个服务器，或者从克隆的仓库运行它进行测试：

1. 克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/claud/claude-code-mcp
cd claude-code-mcp
npm install

2. 配置 MCP 客户端指向本地脚本

{
  "claude_code": {
    "type": "stdio",
    "command": "/绝对路径/claude-code-mcp/start.sh",
    "args": []
  }
}

3. 使用 npm link 进行本地开发

npm run build
npm link

测试与验证

项目包含完整的测试套件：

# 运行所有测试
npm test

# 仅运行单元测试
npm run test:unit

# 运行端到端测试（使用模拟）
npm run test:e2e

# 本地运行端到端测试（需要 Claude CLI）
npm run test:e2e:local

# 开发监视模式
npm run test:watch

# 覆盖率报告
npm run test:coverage

最佳实践总结

1. 始终提供工作目录：对于文件系统或 Git 操作，在提示中明确指定当前工作目录
2. 合理选择权限模式：根据安全需求选择合适的 permissionMode
3. 利用会话管理：对于相关操作使用相同的 sessionId
4. 调试时启用日志：遇到问题时设置 MCP_CLAUDE_DEBUG=true
5. 定期更新：使用最新版本以获得最佳性能和功能

Claude Code MCP Server 为开发者提供了一个强大的桥梁，将 Claude Code 的能力无缝集成到现有的 AI 开发工作流中。通过合理的配置和使用，你可以显著提升开发效率，解决传统 AI 开发工具在处理复杂任务时的局限性。

【免费下载链接】claude-code-mcp Claude Code as one-shot MCP server to have an agent in your agent. 项目地址: https://gitcode.com/gh_mirrors/claud/claude-code-mcp