Claude Code MCP Server

Claude Code MCP 服务

一个 MCP（Model Context Protocol）服务，让 AI 工具能够以编程方式与 Claude Code 交互，从而支持强大的 Agent 间工作流，并提供对话连续性和异步执行支持。

概述

此 MCP 服务在 AI 工具与 Claude Code 之间搭建桥梁，让其他 AI 系统能够通过 Claude Code 执行提示词，同时保留会话状态，确保对话连续性。它同时支持同步和异步执行模式，适用于快速查询和长时间运行的操作。

功能

• 全新对话 - start 工具用于发起新对话（同步/异步）
• 继续对话 - resume 工具用于继续现有对话（同步/异步）
• 工作目录支持 - 可在任意目录中执行 Claude Code（仅限全新对话）
• 任务管理 - 监控任务耗时、取消操作并获取结果
• 对话分支 - 从任意先前的响应 ID 继续，以创建对话分支
• 可靠的 CLI 检测 - 自动查找 Claude Code 安装位置
• 绕过权限 - 使用 --dangerously-skip-permissions 实现完整功能
• 环境配置 - 可通过环境变量自定义
• 调试日志 - 可选的详细日志，便于排查问题
• 模块化架构 - 结构清晰、易于维护的代码库，采用关注点分离设计
• 自动发布 - 用于发布的 GitHub Actions 工作流
• 系统通知 - 任务开始和完成时发送 macOS 通知，并使用不同提示音
• 进程清理 - MCP 服务断开连接时自动清理孤立进程

设计决策

此 MCP 服务采用了有意为之的设计选择，以确保清晰易用，满足实际需求：

响应 ID 与会话 ID

我们使用 “响应 ID” 一词，而非“会话 ID”，因为：

• 每轮对话都会生成一个新的响应 ID
• 你可以从任意先前的响应 ID 创建对话分支
• “会话”一词会让人误以为存在一个连续会话，而实际上每个响应都是一个新的分支点

不支持 --continue 标志

我们有意不支持 Claude Code 的 --continue 标志，因为：

• 多个 Agent 并行运行时，“最近的对话”含义不明确
• 每个 Agent 通常会处理独立的任务
• 使用带有明确响应 ID 的 resume 工具，可精确控制对话

权限模式

目前使用 --dangerously-skip-permissions，其功能等同于 --permission-mode bypassPermissions。此弃用标志将在未来版本中替换为现代权限模式系统，以支持：

• plan 模式，用于只读代码分析
• acceptEdits，用于自动接受文件更改，同时确认危险操作
• default，用于标准交互式提示
• bypassPermissions，用于保持当前行为（授予所有权限）

前置条件

• Node.js 18+ 运行时
• 已安装并配置 Claude Code CLI
• 必须先使用 --dangerously-skip-permissions 运行一次 Claude Code，以接受条款

安装与设置

选项 1：NPX（无需安装）

直接使用 npx：

{
  "mcpServers": {
    "claude": {
      "command": "npx",
      "args": ["claude-mcp"]
    }
  }
}

选项 2：本地开发

1. 克隆并安装：

   git clone https://github.com/ebeloded/claude-mcp.git
   cd claude-mcp
   npm install
   

2. 在 MCP 配置中使用：

   {
     "mcpServers": {
       "claude": {
         "command": "node",
         "args": ["/path/to/claude-mcp/server.js"]
       }
     }
   }
   

Claude Code 首次设置

重要： 使用上述设置前，请先运行一次 Claude Code 以接受权限：

claude --dangerously-skip-permissions

出现提示时接受条款（仅需操作一次）。

配置

MCP 客户端配置

将配置添加到 MCP 配置文件中：

• Cursor： ~/.cursor/mcp.json
• Windsurf： ~/.codeium/windsurf/mcp_config.json

环境变量

• CLAUDE_CLI_NAME：覆盖 Claude CLI 二进制文件名称（默认值：“claude”）
• MCP_CLAUDE_DEBUG：设置为 "true" 以启用详细调试日志
• MCP_NOTIFICATIONS：设置为 "false" 以禁用 macOS 系统通知

工具

start - 全新对话

使用 Claude Code 开启全新对话。支持同步和异步执行。

参数：

• message（字符串，必填）：要发送给 Agent 的消息。请具体说明你的需求，并提及文件路径、所需输出格式和任何限制条件。
• workingDirectory（字符串，可选）：执行时使用的工作目录。可使用绝对路径或相对于当前目录的路径。适用于不同项目或 git worktree。
• appendSystemPrompt（字符串，可选）：要追加到默认系统提示词的文本。
• async（布尔值，可选）：是否异步执行。默认为 true。

示例（同步）：

// Simple query in current directory
start({
  message: "What's 2 + 2?",
  async: false,
})

// Analyze specific code in project directory
start({
  message:
    "Analyze the authentication logic in src/auth.js and list security vulnerabilities as bullet points",
  workingDirectory: "/path/to/project",
  async: false,
})

响应格式（同步）：

4

Response ID: 938c8c6d-1897-4ce4-a727-d001a628a279

示例（异步）：

start({
  message:
    "Analyze the entire codebase for performance bottlenecks, focusing on database queries and API endpoints. Provide specific recommendations with file locations.",
})

start({
  message:
    "Review all React components in src/components/ for accessibility issues and generate a detailed report with WCAG compliance suggestions",
  workingDirectory: "/path/to/frontend-project",
})

响应（异步）：

Task started successfully. Use status with task ID: 550e8400-e29b-41d4-a716-446655440000

resume - 继续对话

继续与 Claude Code 的现有对话。支持同步和异步执行。使用原对话的工作目录。

参数：

• message（字符串，必填）：要发送给 Agent 的消息。需要时可引用此前的上下文——Agent 会记住对话历史。
• previousResponseId（字符串，必填）：此前 Agent 响应中的响应 ID。用于分支或继续任意对话。
• async（布尔值，可选）：是否异步执行。默认为 true。

示例（同步）：

resume({
  message: "What did I just ask you?",
  previousResponseId: "938c8c6d-1897-4ce4-a727-d001a628a279",
  async: false,
})

响应格式（同步）：

You asked me about 2 + 2.

Response ID: b2c3d4e5-f6g7-8901-bcde-f23456789012

示例（异步）：

resume({
  message: "Continue that analysis with more detail",
  previousResponseId: "938c8c6d-1897-4ce4-a727-d001a628a279",
})

响应（异步）：

Task started successfully. Use status with task ID: 661f9511-e30c-41e5-a927-556677889900

status - 任务状态监控

检查异步任务的状态和进度。

参数：

• taskId（字符串，必填）：ask_async 返回的任务 ID

示例：

status({
  taskId: "550e8400-e29b-41d4-a716-446655440000",
})

响应（运行中）：

Task 550e8400-e29b-41d4-a716-446655440000:
Status: running
Elapsed: 45s
Working Directory: /Users/ebeloded/Code/claude-mcp
Created: 2025-05-28T21:15:30.123Z
Updated: 2025-05-28T21:16:15.456Z

响应（已完成）：

Task 550e8400-e29b-41d4-a716-446655440000:
Status: completed
Elapsed: 1m 52s
Working Directory: /Users/ebeloded/Code/claude-mcp
Created: 2025-05-28T21:15:30.123Z
Updated: 2025-05-28T21:17:22.789Z

Result: [Claude's comprehensive analysis here...]
Response ID: 938c8c6d-1897-4ce4-a727-d001a628a279
Cost: $0.045
Duration: 112456ms

cancel - 取消任务

取消正在运行的异步任务。

参数：

• taskId（字符串，必填）：要取消的任务 ID

示例：

cancel({
  taskId: "550e8400-e29b-41d4-a716-446655440000",
})

响应：

Task 550e8400-e29b-41d4-a716-446655440000 cancelled successfully

架构

该服务采用模块化架构，便于维护：

claude-mcp/
├── server.js                    # Main entry point & orchestration
├── src/
│   ├── server/
│   │   └── setup.js             # MCP server setup and signal handling
│   ├── services/
│   │   ├── TaskService.js       # Async task lifecycle & notification management
│   │   └── ClaudeService.js     # Claude CLI execution logic
│   ├── tools/
│   │   └── (MCP tool definitions)
│   └── utils/
│       ├── errors.js            # Error handling utilities
│       ├── logger.js            # Debug logging utilities
│       └── validation.js       # Input validation utilities
└── tests/
    └── *.e2e.test.ts            # End-to-end tests

组件职责

• TaskService：负责异步任务的创建、跟踪、进度监控、取消、清理和系统通知
• ClaudeService：负责 Claude CLI 的发现和执行，支持同步与异步模式，并管理进程组
• Setup：负责 MCP 服务初始化、信号处理和协调优雅关闭
• Tools：使用 MCP SDK 模式，在 server.js 中直接注册六个 MCP 工具
• Server：精简的编排层，将各组件连接起来

开发

测试

npm test

测试套件包括：

• 带会话管理的同步执行
• 异步任务创建和状态监控
• 任务取消功能
• 边缘情况的错误处理

调试模式

设置 MCP_CLAUDE_DEBUG=true 以启用详细日志：

{
  "mcpServers": {
    "claude": {
      "command": "node",
      "args": ["/path/to/claude-mcp/server.js"],
      "env": {
        "MCP_CLAUDE_DEBUG": "true"
      }
    }
  }
}

本地开发

# Install dependencies
npm install

# Run tests
npm test

# Start in debug mode
MCP_CLAUDE_DEBUG=true npm start

STDIO 日志记录（重要）

此服务通过 STDIO 通信。请勿将常规日志写入 stdout，否则会破坏 JSON-RPC。所有日志都通过 logger 工具写入 stderr。有关日志记录，请参阅 MCP 快速入门指南：https://modelcontextprotocol.io/quickstart/server.md

使用场景

全新对话（start）

• 开启新对话或进行分析
• 使用不同的代码库（通过 workingDirectory）
• 快速查询并立即获得响应（同步模式）
• 需要非阻塞执行的长时间操作（异步模式）
• 分析位于不同目录或 git worktree 中的项目
• 为特定行为自定义系统提示词

恢复对话（resume）

• 继续现有对话和上下文
• 在之前的回复或分析基础上继续
• 针对先前上下文提出后续问题
• 从任意先前回复分支出新对话
• 在同一工作目录中保持对话连续性
• 支持同步和异步执行模式

编写有效的提示词

每个工具都会在参数说明中提供详细的消息指导，帮助你从 Claude Code 获得最佳结果。关键原则如下：

• 具体说明你希望分析或创建的内容
• 注明文件路径和目录，以便 Claude 聚焦于相关内容
• 指定输出格式（要点、JSON、代码片段等）
• 列出约束条件和关注领域（性能、安全性、无障碍性等）
• 对于恢复工具：引用先前上下文并逐步推进

请参阅工具参数说明，了解全面的指导和示例。

发布

此项目使用 GitHub Actions 自动发布：

• 版本发布：创建 GitHub release，即可自动发布到 npm
• 手动发布：使用“Publish to npm”工作流 dispatch 手动发布

许可证

MIT

贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 适用时添加测试
5. 提交 pull request

故障排除

未找到 Claude CLI

• 确保已安装 Claude CLI，并且它位于 PATH 中
• 如果使用自定义二进制文件名，请设置 CLAUDE_CLI_NAME 环境变量
• 检查 CLI 是否正常运行：claude --version

权限错误

• 运行一次 claude --dangerously-skip-permissions 以接受条款
• 确保 MCP 服务有权执行 Claude CLI

对话连续性问题

• 每个响应都会返回响应 ID，请保存这些 ID 以便继续对话
• 对话可能会在长时间不活动后过期
• 每个未提供 previousResponseId 的新对话都会从头开始
• 你可以从任意先前响应 ID 分支出新对话

异步任务问题

• 任务完成 1 小时后会自动清理
• 使用 status 监控长时间运行的任务
• 如有需要，可使用 cancel 取消任务
• 如果任务似乎卡住，请检查调试日志
• MCP 服务断开连接时，任务会自动取消

系统通知

• macOS 通知会显示任务开始（“Agent Task Started”）和完成（“Agent Task Completed”）
• 开始时播放 Tink 音效，完成时根据结果播放 Glass、Basso 或 Funk 音效
• 设置 MCP_NOTIFICATIONS=false 环境变量即可禁用通知
• 通知会包含截断后的提示词文本，便于了解上下文

性能注意事项

• 异步任务不会阻塞 MCP 服务
• 可以并发运行多个异步任务
• 监控任务进度，避免资源耗尽
• 对于运行时间很长的操作，可考虑取消任务
• 父进程监控可防止出现孤立进程