MCP Server Manager for Cursor

Cursor 的 MCP 服务管理器

面向 Cursor 的 MCP（Model Context Protocol）工作区管理器。本项目简化了在本地开发环境中管理多个 MCP 服务时往往繁琐的工作流。它提供统一、一致的配置方式和 CLI（命令行界面），可同时或单独启动、停止、更新所有 MCP 服务并检查其状态。它还会自动管理 Cursor 的全局（或本地）MCP 配置，配置文件为 mcp.json。

你可以通过 deno task 命令（例如 deno task start）运行 CLI，也可以直接用 deno run -A src/mod.ts <command> [options] 执行主模块。

项目概述

用途

管理各自配置方式和运行特性各不相同的 MCP 服务可能很麻烦。本项目将这些管理工作集中到一处。只需定义一次所有服务，然后使用简单的命令进行控制。无论 MCP 服务通过 HTTP/SSE 还是 STDIO 通信，此管理器都会以统一的方式处理。

开始使用

注意

刚接触 MCPS？ 你需要了解自己在做什么，在企业环境中尤其如此。继续之前，请阅读如何安全地使用 MCP。

开始使用 MCP 服务管理器时，你主要会与服务定义和环境设置打交道。以下是主要组件概览：

• 服务配置文件：位于 servers/ 目录中，这些 TypeScript 文件（例如 mcp-myservice.config.ts）定义各个 MCP 服务的属性。你可以使用 examples/ 目录中的模板作为起点（例如，HTTP/SSE 服务可使用 examples/mcp-atlassian.ts.example，STDIO 服务可使用 examples/mcp-slack.ts.example）。
• 环境变量：敏感凭据和服务专属设置存储在 .env 文件中（例如 servers/config/mcp-myservice.env）。examples/ 目录中提供了示例环境文件（例如 examples/mcp-myservice.env.example），供你参考。
• 全局管理器设置：servers/config/main.env 文件用于控制全局行为，例如通过 ENABLED_SERVERS 变量指定启用哪些服务。

关于创建和配置新服务的详细分步说明，请参阅主工作流中的添加新的 MCP 服务部分。

提示

为了获得最佳使用体验，建议分叉此代码库，以安全地管理个人 MCP 服务配置。若要更轻松地访问 CLI，可以将 src/mod.ts 添加为 PATH 别名，或在其他项目中创建指向 src/mod.ts 的 Cursor 规则。

什么是 MCP 服务？

Model Context Protocol（MCP）服务是 Cursor 与外部服务或工具之间的桥梁。它通过开放一组标准化的“工具”，让 Cursor 能够访问并使用这些服务中的数据或功能（例如 Jira、Slack、Confluence 等）。借助这些工具，你可以通过自然语言或特定命令，直接在 IDE 中获取 Jira 问题、搜索 Confluence 页面或发送 Slack 消息。

状态管理

MCP 服务管理器会在 data/state.json 状态文件中跟踪已配置服务的状态（例如 HTTP 服务当前是否正在运行）。此文件由 CLI 自动管理。

主要工作流

添加新的 MCP 服务

1. 创建配置文件：
   • 前往 examples/ 目录并选择一个模板：
     • 对于 HTTP/SSE 服务：mcp-atlassian.ts.example
     • 对于 STDIO 服务：mcp-slack.ts.example
   • 将所选模板文件复制到 servers/ 目录。
   • 重命名复制后的文件以反映新服务，例如 mcp-myservice.config.ts。
2. 编辑配置：
   • 打开新服务的配置文件（例如 mcp-myservice.config.ts）。
   • 更新 name、description、type（http 或 stdio）、image 和 args 字段。
   • MCP 管理器会根据你设置的服务 name 自动使用环境文件（例如 servers/config/mcp-myservice.env）。
   • 对于 HTTP/SSE 服务：
     • 你可以选择在 args 数组中加入 --port PORT，以指定固定端口。
     • 如果未指定端口，管理器会在启动服务时自动分配一个可用端口。
   • 配置 healthValidator 部分，以定义如何检查服务的健康状态。此标准化配置同时适用于 HTTP 和 STDIO 服务。示例如下：

     healthValidator: {
       method: "mcp/tools/list", // 要调用的 MCP 方法
       params: {},               // 方法的参数
       responseContains: "tools", // 响应中必须包含的可选字符串
       timeoutMs: 5000           // 超时时间（毫秒）
     }
     

   • 在 postStartInstructions 属性中加入测试提示词示例，指导用户如何在服务运行后进行测试。
3. 创建环境文件：
   • 在 examples/ 中创建环境文件示例（例如 examples/mcp-myservice.env.example），列出所有必需的环境变量并填写占位值。
   • 在 servers/config/ 目录中创建实际的环境文件（例如 servers/config/mcp-myservice.env），复制示例文件并填入实际凭据和设置。
   • 重要：如果实际环境文件尚未被 .gitignore 中的通用规则（例如 servers/config/*.env）涵盖，请将其添加到 .gitignore，以避免提交敏感凭据。
4. 测试：
   • 现在，你可以使用通用工作流（例如运行 deno task start 启动服务）来管理新服务。

HTTP 服务配置示例：

const serverConfig: McpServerConfig = {
  name: 'mcp-atlassian',
  description: 'MCP Atlassian Connector',
  type: 'http',
  image: 'ghcr.io/sooperset/mcp-atlassian:latest',
  args: [
    '--transport',
    'sse',
    // Port will be automatically assigned if not specified
    // '--port',
    // '9000',
    '-vv',
  ],

  healthValidator: {
    method: 'mcp/tools/list',
    params: {},
    responseContains: 'tools',
    timeoutMs: 5000,
  },

  postStartInstructions: `
Atlassian MCP server is now running!
You can now use Jira and Confluence tools in Cursor.
Make sure your Atlassian credentials are properly configured in your .env file.
Try using the jira_list_projects tool to retrieve all the Jira projects I have access to and format the output as a bulleted list
`,
}

STDIO 服务配置示例：

const serverConfig: McpServerConfig = {
  name: 'mcp-slack',
  description: 'MCP Slack Connector',
  type: 'stdio',
  image: 'mcp/slack',
  args: [], // No additional args needed for STDIO servers
  // The orchestrator will add the necessary Docker args

  healthValidator: {
    method: 'slack_get_users',
    params: { limit: 1 },
    timeoutMs: 10000,
  },

  postStartInstructions: `
NOTE: The Slack MCP server is designed to run in interactive mode.
Cursor will run the server as needed, so no persistent container is needed.
You can now use Slack tools in Cursor.
Try using the command: List all channels in the Slack workspace
`,
}

编辑 MCP 服务

要编辑现有 MCP 服务：

1. 修改其在 servers/ 中的配置文件。
2. 如有必要，更新其在 servers/config/ 中对应的环境文件。 下次运行命令时（例如 deno task start），更改将生效。

移除 MCP 服务

要移除 MCP 服务：

1. 从 servers/ 中删除其配置文件。
2. （可选）从 servers/config/ 和 examples/ 中删除其环境文件。 CLI 将不再管理该服务。

通用工作流（CLI 命令）

所有命令都可以针对所有已配置的服务运行，也可以使用 --server=<server-name> 标志指定某个服务运行（例如，deno task start --server=mcp-atlassian）。

• 启动服务：

  deno task start
  # or to start a specific server:
  deno task start --server=mcp-myservice
  

  此命令会启动已配置的 MCP 服务。对于 HTTP 服务，它会启动 Docker 容器；如果配置中未指定端口，则会自动分配一个可用端口。对于 STDIO 服务，它会验证配置。成功启动后，CLI 会询问你是否要使用服务设置自动更新 Cursor 配置文件。如果你拒绝，它会显示所需的 JSON 配置，供你手动添加。

  # To see how the Cursor MCP config would change without making changes:
  deno task start --dry-run
  # or for a specific server:
  deno task start --server=mcp-myservice --dry-run
  # dedicated dry-run task:
  deno task start:dry-run
  

  --dry-run 标志会显示对 Cursor MCP 配置文件进行哪些更改，但不会实际执行这些更改。它会并列显示当前配置，以及启动服务后配置将呈现的样子。

• 停止服务：

  deno task stop
  # or to stop a specific server:
  deno task stop --server=mcp-myservice
  

  此命令会停止所有正在运行的 HTTP MCP 服务容器。STDIO 服务不会持续运行，因此此命令主要影响 HTTP 类型的服务。CLI 会自动更新 Cursor 配置文件，以反映服务已停止运行，确保 Cursor 与服务的实际状态保持同步。

  # To see how the Cursor MCP config would change without making changes:
  deno task stop --dry-run
  # or for a specific server:
  deno task stop --server=mcp-myservice --dry-run
  # dedicated dry-run task:
  deno task stop:dry-run
  

  与启动命令类似，--dry-run 标志会显示对 Cursor MCP 配置文件进行哪些更改，但不会实际执行这些更改，也不会停止任何服务。

• 检查服务状态：

  deno task status
  # or for a specific server:
  deno task status --server=mcp-myservice
  

  显示所有已配置 MCP 服务的当前状态（例如，运行中、已停止，或 STDIO 服务的验证状态）。

• 查看服务日志：

  deno task logs
  # or for a specific server:
  deno task logs --server=mcp-myservice
  

  显示正在运行的 HTTP MCP 服务容器的最近 100 行日志。你可以使用此功能排查问题或监控服务活动。

  # To continuously stream logs in real-time:
  deno task logs --stream
  # or for a specific server:
  deno task logs --server=mcp-myservice --stream
  # dedicated streaming task:
  deno task logs:stream
  

  --stream 标志会启用实时日志流，与 docker logs --follow 类似。调试问题或实时查看服务活动时，此功能尤其有用。按 Ctrl+C 退出流式模式。

• 执行运行状况检查：

  deno task health-check
  # or for a specific server:
  deno task health-check --server=mcp-myservice
  

  对于 HTTP 服务，此命令会检查正在运行的容器是否响应正常且运行健康。对于 STDIO 服务，它会重新执行验证。

• 更新服务镜像：

  deno task update
  # or for a specific server:
  deno task update --server=mcp-myservice
  

  根据配置文件中的定义，拉取指定服务的最新 Docker 镜像。

MCP 服务类型

此管理器支持两种 MCP 服务类型，通过配置中的 type 属性进行区分：

1. HTTP/SSE 服务（例如，Atlassian MCP）

• 在此代码库中的工作方式：
  • 这些服务作为持久运行的 Docker 容器在后台运行。
  • 此管理器会启动 Docker 容器、映射所需端口，并使用标准化的 healthValidator 配置执行运行状况检查。
  • 身份验证和特定于服务的逻辑由 Docker 镜像本身处理，并通过与服务关联的 .env 文件传入环境变量进行配置。
• Cursor 配置：
  • Cursor 通过 URL（例如，http://localhost:9000/sse）连接这些服务。
  • 如果在服务配置的 args 中指定端口，管理器就会使用该端口。
  • 如果未指定端口，服务启动时管理器会自动分配一个可用端口。
  • 服务成功启动后，CLI 会询问你是否要使用相应设置自动更新 Cursor MCP 配置文件。
  • 如果你倾向于手动配置，CLI 会提供要添加到 Cursor 设置中的准确 JSON 片段。

2. STDIO 服务（例如 Slack MCP）

• 在此代码库中的工作方式：
  • 这些服务旨在由 Cursor 按需启动，并通过标准输入/输出（STDIO）进行通信。
  • 它们不会作为持久的后台服务运行。使用 STDIO 服务的 deno task start 命令时，此管理器只会临时启动 Docker 容器，仅用于验证 配置和凭据（来自其 .env 文件）是否正确，验证过程使用 healthValidator 配置。随后容器会退出。这是预期行为。
• Cursor 配置：
  • STDIO 服务的 Cursor 配置包含用于交互式运行容器的 command（例如 docker）和 args 数组。
  • 管理器会自动添加 --env-file 标志，指向你的环境文件，因此无需在配置中硬编码凭据。
  • 验证成功后，CLI 会提示你自动使用相应设置更新 Cursor MCP 配置文件。
  • 如果你更倾向于手动配置，CLI 会提供一个 Cursor 的 JSON 片段模板。

健康验证

HTTP 和 STDIO 服务都可以使用标准化的健康验证机制：

healthValidator: {
  method: "mcp/tools/list",    // MCP method to call
  params: {},                  // Parameters for the method
  responseContains: "tools",   // Optional string that must be in the response
  timeoutMs: 5000              // Timeout in milliseconds
}

• healthValidator 属性为可选项。如果未指定（null、false 或 undefined），则会跳过健康检查，并返回成功状态。
• 配置后，验证器会使用提供的方法和参数构造 JSON-RPC 2.0 请求
• 对于 HTTP 服务，请求会发送到服务的端点
• 对于 STDIO 服务，请求会通过 Docker STDIO 发送到服务
• 系统会检查响应是否包含错误，并可选择检查响应中是否包含特定字符串
• 这种统一方式简化了服务配置，并确保所有服务类型的健康检查保持一致

健康验证系统还支持传递给验证器的 silent 选项，用于在跳过健康检查时抑制日志消息。CLI 主要在不需要详细日志的情况下检查服务状态时，于内部使用此选项。

高层架构

MCP Server Manager 采用配置驱动的设计：

• 服务配置（servers/*.config.ts）：这些 TypeScript 文件是系统的核心。每个文件定义一个 MCP 服务，包含以下属性：
  • name：服务的唯一标识符
  • description：易于理解的描述
  • type：http 或 stdio
  • image：要使用的 Docker 镜像
  • args：命令行参数（对于 HTTP 服务，包含 --port 参数）
  • healthValidator：健康检查的可选配置
  • postStartInstructions：服务启动后显示给用户的说明，包括使用命令示例
• 环境文件（servers/config/*.env 和 examples/*.env.example）：凭据和服务专属设置存储在 .env 文件中，与主配置分开。这可以避免敏感数据进入版本控制。
• 核心逻辑（src/）：
  • mod.ts：CLI 的主入口点。
  • config.ts：从 servers/ 目录加载所有服务配置。
  • types.ts：定义服务配置（例如 McpServerConfig）和状态的 TypeScript 类型与接口。
  • orchestrator.ts：包含 transformServerConfigForCursor 函数，用于将服务配置转换为 Cursor MCP 条目。
  • commands/start.ts：实现主 start 命令逻辑，解析参数并协调操作。
  • commands/stop.ts、commands/status.ts、commands/health-check.ts：实现各自操作的逻辑。
  • services/cursor-service.ts：管理 Cursor MCP 配置文件的读取和写入。
  • services/docker-service.ts：处理与 Docker CLI 的所有交互（拉取镜像、运行／停止容器、检查状态）。
  • services/health-validator-service.ts：包含用于 HTTP 和 STDIO 服务的标准化健康验证逻辑。
• Deno 任务（deno.jsonc）：为常用的 CLI 命令提供便捷快捷方式（例如 deno task start）。

用户主要与 servers/ 中的配置文件及其对应的 .env 文件交互。src/ 目录包含使整个系统运行的底层机制。

故障排除

• 检查日志：CLI 会提供详细的日志。如需更详细的输出，可以调整 servers/config/main.env 中的 LOG_LEVEL。
  • 如需查看特定服务的日志，请使用 logs 命令：deno task logs --server=mcp-myservice；也可以使用 deno task logs --stream 实时查看日志。
  • 这样可以直接访问容器日志，其中通常包含错误详情和调试信息。
• servers/config/main.env：此文件包含 MCP 管理器本身的全局设置：
  • DENO_ENV：设置为 development，以获得更详细的输出或启用可能仅限开发环境的行为。
  • LOG_LEVEL：控制日志的详细程度。可以设置为 debug、info、warn 或 error。排查问题时，通常使用 debug 会有所帮助。
  • ENABLED_SERVERS：以逗号分隔的服务名称列表，指定可供管理的服务。例如：ENABLED_SERVERS=github-mcp-server, mcp-atlassian, mcp-slack。如果未指定，则会启用 servers/ 目录中的所有服务。这样无需删除配置文件，即可选择性地启用或禁用服务。
  • CURSOR_MCP_CONFIG_PATH：指定存储 Cursor 的 MCP 服务配置的文件路径。默认情况下，此路径指向全局 Cursor 配置文件（例如，~/.cursor/mcp.json）。如果希望按项目管理 MCP 配置，可以将此路径改为项目专用路径，例如当前项目工作区中的 .cursor/mcp.json。启动服务时，系统会使用此路径自动更新 Cursor 配置。
• Docker 问题：
  • 确保已安装并运行 Docker。CLI 会尝试检查这一点，但手动确认也会有所帮助。
  • 对于 HTTP 服务，如果服务启动失败或运行状态不健康，请使用 docker ps 检查容器是否正在运行，并使用 docker logs <container_name>（例如，docker logs mcp-atlassian）检查日志中是否有错误。
• 环境变量：仔细检查特定服务的 .env 文件（例如，servers/config/mcp-atlassian.env），确保文件名正确、位于 servers/config/ 目录中，并包含 MCP 服务镜像所需的正确凭据和设置。
• 找不到服务错误：如果使用 --server 标志时收到服务未启用的错误，请检查 servers/config/main.env 中的 ENABLED_SERVERS 变量是否包含该服务名称。
• Cursor 配置问题：如果自动配置不起作用，请确保正确设置了 CURSOR_MCP_CONFIG_PATH 环境变量，并且该变量指向有效的文件路径。默认路径为 ~/.cursor/mcp.json，但可能因操作系统和 Cursor 安装位置而异。

Cursor 配置同步

MCP Server Manager 会使 Cursor MCP 配置文件与实际服务状态保持同步：

• 服务以动态分配的端口启动时，端口会保存到状态文件和 Cursor 配置中
• 服务停止时，Cursor 配置会更新，以反映服务离线状态
• 服务配置（参数、命令等）更改时，Cursor 配置会自动更新
• 配置文件路径由 servers/config/main.env 中的 CURSOR_MCP_CONFIG_PATH 环境变量决定

这样可以确保 Cursor 始终拥有 MCP 服务的最新信息，即使端口发生变化，或服务启动和停止也是如此。