Claude Code MCP Server 使用指南

一、准备工作：环境搭建与依赖配置

1.1 系统环境要求

✅ Node.js 版本：v20 或更高（推荐使用 fnm 或 nvm 管理版本）
✅ Claude CLI：需提前安装并接受权限（执行 claude --dangerously-skip-permissions 完成首次配置）
⚠️ 权限说明：首次运行需手动接受 --dangerously-skip-permissions 标志，否则 MCP 服务将无法正常调用 Claude 功能

1.2 项目获取与安装

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

💡 专业提示：若需使用自定义 Claude CLI 路径，可通过 CLAUDE_CLI_NAME 环境变量指定绝对路径（如 /usr/local/bin/claude-custom），相对路径将被拒绝。

二、核心功能：工具链与应用场景

2.1 多模态代码工具链

Claude Code MCP 提供统一的 claude_code 工具，支持以下核心操作：

• 代码生成与重构：生成 Python/JavaScript 等代码，优化现有函数逻辑
• 文件系统管理：创建/编辑/移动文件，支持模糊路径匹配
• Git 工作流：提交代码、创建分支、推送标签等版本控制操作
• 终端命令执行：运行 npm build、ls 等系统命令

图 1：使用 Claude Code 提取环境变量并执行构建命令的多步骤流程

2.2 企业级应用场景

• 团队协作：配置共享 workFolder 路径，实现多人协作时的文件操作一致性
• CI/CD 集成：通过 MCP 工具自动更新 package.json 版本号并生成 CHANGELOG
• 安全审计：批量扫描项目文件中的敏感环境变量（如 API 密钥）

💡 专业提示：复杂任务建议拆分为步骤式指令，例如："1. 更新 package.json 版本号至 2.0.0；2. 添加 CHANGELOG 记录；3. 提交并推送变更"。

三、实战配置：高级技巧与问题解决

3.1 环境变量优先级控制

配置参数按以下优先级生效（由高到低）：

1. 命令行临时变量：运行时通过 MCP_CLAUDE_DEBUG=true npm start 动态设置
2. mcp.json 配置：在客户端配置文件的 env 字段中定义
3. 系统环境变量：全局设置的 CLAUDE_CLI_PATH 等变量

3.2 配置文件热加载方案

当修改 MCP 客户端配置（如 mcp.json）后，无需重启服务： ✅ 发送空工具调用触发配置刷新：{"toolName":"claude_code","arguments":{"prompt":""}}
✅ 验证方法：检查服务日志中的 [Debug] Reloaded configuration 提示

图 2：使用 Claude Code 扫描并迁移文档中的图片引用路径

3.3 常见问题排查

问题现象	可能原因	解决方法
"Claude CLI 未找到"	路径配置错误	执行 which claude 确认 CLI 位置，设置 CLAUDE_CLI_NAME 绝对路径
权限拒绝错误	未完成首次手动授权	运行 claude --dangerously-skip-permissions 并接受条款
命令超时	任务过于复杂	将大任务拆分为小步骤，设置 MCP_CLAUDE_DEBUG=true 查看详细日志

💡 专业提示：生产环境建议设置 MCP_CLAUDE_DEBUG=false，避免日志干扰 JSON 解析；调试时开启可查看 CLI 调用细节。

四、快速启动与验证

4.1 启动服务

# 开发模式
npm run dev

# 生产模式
npm run build && npm start

4.2 功能验证

发送测试请求验证服务可用性：

{
  "toolName": "claude_code",
  "arguments": {
    "prompt": "列出当前目录文件",
    "workFolder": "/path/to/project"
  }
}

✅ 预期结果：返回目录文件列表，无权限弹窗干扰。

通过以上配置，您可以充分利用 Claude Code MCP Server 的自动化能力，提升开发效率并简化复杂工作流。详细 API 文档请参考项目 docs/ 目录下的说明文件。