用于游标的MCP服务器管理器

用于Cursor的MCP（模型上下文协议）工作区管理器。该项目简化了在本地开发环境中管理多个MCP服务器的繁琐工作流程。它提供了一种一致、统一的配置方法和CLI（命令行界面），用于一次或单独启动、停止、更新和检查所有MCP服务器的状态。它还可以自动管理您的全局（或本地）游标 MCP配置在……里面 mcp.json.

您可以使用以下命令运行CLI deno task 命令（例如。， deno task start)或者通过直接执行主模块 deno run -A src/mod.ts [options].

项目概述

目的

管理各种MCP服务器，每个服务器都有自己的设置和操作怪癖，可能会很麻烦。这个项目集中了这种管理。定义所有服务器一次，然后使用简单的命令来控制它们。无论MCP服务器是通过HTTP/SSE还是STDIO进行通信，此管理器都会一致地处理它们。

入门指南

\[！小心\]MCPS新手？你需要知道自己在做什么，尤其是在企业环境中。阅读如何安全地使用MCP 在你走得更远之前。

要开始使用MCP服务器管理器，您将主要与服务器定义和环境设置进行交互。以下是关键组件的概述：

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

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

\[！提示\] 为了优化使用，请分叉此存储库以安全地管理您的个人MCP服务器配置。为了便于CLI访问，别名 src/mod.ts 到您的PATH，或在其他项目中创建一个指向的游标规则 src/mod.ts.

什么是MCP服务器？

模型上下文协议（MCP）服务器充当Cursor和外部服务或工具之间的桥梁。它允许Cursor通过公开一组Cursor可以调用的标准化“工具”来访问和交互这些服务（如Jira、Slack、Confluence等）中的数据或功能。这启用了检索Jira问题、搜索Confluence页面或通过自然语言或特定命令直接从IDE发送Slack消息等功能。

状态管理

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

主要工作流程

添加新的MCP服务器

创建配置文件:

- 导航到 examples/ 目录并选择模板： - 对于HTTP/SSE服务器： mcp-atlassian.ts.example - 对于STDIO服务器： mcp-slack.ts.example - 将所选模板文件复制到 servers/ 目录。 - 重命名复制的文件以反映您的新服务器，例如， mcp-myservice.config.ts.

编辑配置:

- 打开新的服务器配置文件（例如。， mcp-myservice.config.ts). - 更新 name, description, type (http 或 stdio), image，以及 args 领域。 - 环境文件（例如。， servers/config/mcp-myservice.env)由MCP管理器根据服务器自动使用 name 你设置。 - 对于HTTP/SSE服务器： - 您可以选择包括 --port PORT 在你的 args array指定固定端口。 - 如果没有指定端口，管理器将在启动服务器时自动分配一个可用端口。 - 配置 healthValidator 部分定义如何检查服务器的健康状况。这种标准化配置适用于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
     }

- 在中包含测试提示示例 postStartInstructions 属性，指导用户如何在服务器运行后进行测试。

创建环境文件:

- 在中创建示例环境文件 examples/ （例如。， examples/mcp-myservice.env.example)列出所有必需的环境变量及其占位符值。 - 在中创建您的实际环境文件 servers/config/ 目录（例如。， servers/config/mcp-myservice.env)通过复制示例并填写您的实际凭据和设置。 - 重要：将您的实际环境文件添加到您的 .gitignore 如果它还没有被一个通用的模式所覆盖，比如 servers/config/*.env 以避免提交敏感凭据。

测试:

- 您现在可以使用一般工作流程（比如 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服务器，请执行以下操作：

在中修改其配置文件 servers/.
在中更新其相应的环境文件 servers/config/ 如有必要。

这些更改将在您下次运行命令时被拾取（例如。， deno task start).

删除MCP服务器

要删除MCP服务器，请执行以下操作：

从中删除其配置文件 servers/.
（可选）从中删除其环境文件 servers/config/ 和 examples/.

服务器将不再由CLI管理。

通用工作流（CLI命令）

所有命令都可以针对所有配置的服务器或使用 --server= 标志（例如。， 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

与start命令类似 --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 与服务器关联的文件。

光标配置:

- 游标通过URL连接到这些服务器（例如。， http://localhost:9000/sse). - 如果在服务器配置中指定端口 args，经理将使用该端口。 - 如果没有指定端口，管理器将在服务器启动时自动分配一个可用端口。 - 当服务器成功启动时，CLI将提供使用适当设置自动更新Cursor MCP配置文件的功能。 - 如果您更喜欢手动配置，CLI将提供精确的JSON代码段以添加到您的游标设置中。

2.STDIO服务器（例如Slack MCP）

它们在这个代码库中是如何工作的:

- 这些服务器被设计为由Cursor按需启动，并通过标准输入/输出（STDIO）进行通信。 - 他们确实如此不作为持久后台服务运行。当你使用 deno task start 对于STDIO服务器的命令，此管理器会临时启动Docker容器 _仅用于验证_ 配置和凭据（来自 .env 文件）正确使用 healthValidator 配置。然后，容器将退出。这是预期的行为。

光标配置:

- STDIO服务器的游标配置包括 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服务器管理器采用配置驱动的方法设计：

**服务器配置(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：定义服务器配置的TypeScript类型和接口（如 McpServerConfig)和国家。 - orchestrator.ts：包含 transformServerConfigForCursor 将服务器配置转换为游标MCP条目的函数。 - commands/start.ts：实现main 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)：提供方便的快捷方式（如 deno task start)对于常见的CLI命令。

用户主要与中的配置文件进行交互 servers/ 及其对应 .env 文件夹。这 src/ 目录包含使其正常工作的底层机制。

故障排除

检查日志：CLI提供信息丰富的日志。要获得更详细的输出，您可以调整 LOG_LEVEL 在……里面 servers/config/main.env.

- 对于特定于服务器的日志，请使用 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：指定存储MCP服务器游标配置的文件路径。默认情况下这指向全局游标配置文件（例如。， ~/.cursor/mcp.json).您可以覆盖此选项以使用特定于项目的路径，例如 .cursor/mcp.json 如果您希望在每个项目的基础上管理MCP配置，请在当前的项目工作区中。此路径用于启动服务器时自动更新游标配置。

Docker问题:

- 确保Docker已安装并正在运行。CLI会尝试检查这一点，但手动验证会有所帮助。 - 对于HTTP服务器，如果服务器无法启动或不正常，请使用 docker ps 查看容器是否正在运行 docker logs （例如。， docker logs mcp-atlassian)检查其日志是否有错误。

环境变量：仔细检查您的服务器是否特定 .env 文件（例如。， servers/config/mcp-atlassian.env)名称正确，位于 servers/config/ 目录，并包含MCP服务器映像所需的正确凭据和设置。
找不到服务器错误：如果您在使用时收到一个错误，说明服务器未启用 --server 标记，检查服务器名称是否列在 ENABLED_SERVERS 变量in servers/config/main.env.
游标配置问题：如果自动配置不起作用，请确保 CURSOR_MCP_CONFIG_PATH 环境变量设置正确，并指向有效的文件位置。默认路径为 ~/.cursor/mcp.json，但这可能因您的操作系统和Cursor安装而异。

光标配置同步

MCP服务器管理器使Cursor MCP配置文件与实际服务器状态保持同步：

当服务器开始使用动态分配的端口，该端口将保存到状态文件和Cursor的配置中
当服务器停止，更新Cursor的配置以反映脱机状态
服务器配置时变化（args、command等），游标的配置会自动更新
配置文件路径由 CURSOR_MCP_CONFIG_PATH 环境变量 servers/config/main.env

这确保了Cursor始终拥有有关MCP服务器的最新信息，即使在端口更改或服务器启动和停止时也是如此。

Cursor MCP Manager

快速接入

详细介绍