在 Roo Code 中使用 MCP

对 MCP 服务器感到困惑？

MCP（Model Context Protocol）服务器充当桥梁，为 Roo Code 提供更广泛的工具和外部服务（如数据库、API 或自定义脚本）的访问权限。它使用标准通信方法，允许 Roo 利用这些外部功能。

如需深入了解，请查看什么是 MCP？。

Model Context Protocol (MCP) 通过连接外部工具和服务来扩展 Roo Code 的功能。本指南涵盖在 Roo Code 中使用 MCP 所需了解的所有内容。

配置 MCP 服务器

MCP 服务器配置可以在两个级别管理：

全局配置：存储在 mcp_settings.json 文件中，可通过 VS Code 设置访问（见下文）。这些设置在所有工作区中生效，除非被项目级配置覆盖。
项目级配置：在项目根目录的 .roo/mcp.json 文件中定义。这允许您为特定项目设置服务器，并通过将文件提交到版本控制与团队共享配置。Roo Code 会自动检测并加载此文件（如果存在）。

优先级：如果服务器名称在全局和项目配置中都存在，项目级配置优先。

编辑 MCP 设置文件

您可以直接从 Roo Code MCP 设置视图编辑全局和项目级 MCP 配置文件：

点击 Roo Code 窗格顶部导航中的图标。

滚动到 MCP 设置视图底部。
点击相应的按钮：
- Edit Global MCP：打开全局 mcp_settings.json 文件。
- Edit Project MCP：打开项目特定的 .roo/mcp.json 文件。如果此文件不存在，Roo Code 将为您创建它。

两个文件都使用 JSON 格式，包含 mcpServers 对象，其中包含命名的服务器配置：

{
  "mcpServers": {
    "server1": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

Roo Code 中 MCP 服务器配置示例（STDIO 传输）

理解传输类型

MCP 支持三种服务器通信传输类型：用于本地服务器的 STDIO、用于新远程服务器的流式 HTTP（推荐），以及用于旧远程服务器的 SSE（Server-Sent Events）。

STDIO 传输

用于在本地机器上运行的本地服务器：

通过标准输入/输出流通信
延迟较低（无网络开销）
安全性更好（无网络暴露）
设置更简单（无需 HTTP 服务器）
作为子进程在您的机器上运行

有关 STDIO 传输工作原理的更深入信息，请参阅 STDIO 传输。

STDIO 配置参数：

command（必需）：要运行的可执行文件（例如 node、python、npx 或绝对路径）。
args（可选）：传递给命令的字符串参数数组。您可以使用 ${env:VARIABLE_NAME} 语法引用系统环境变量。
cwd（可选）：启动服务器进程的工作目录。如果省略，默认为第一个工作区文件夹路径或主进程的工作目录。如果服务器脚本依赖相对路径，这很有用。
env（可选）：为服务器进程设置的环境变量对象。
alwaysAllow（可选）：从此服务器自动批准的工具名称数组。
disabled（可选）：设置为 true 以禁用此服务器配置。

STDIO 配置示例：

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/path/to/project/root", // 可选：指定工作目录
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

在参数中使用系统环境变量

您可以在 args 数组中使用 ${env:VARIABLE_NAME} 语法引用系统级环境变量。这允许您从系统环境传递敏感信息（如 API 密钥或令牌），而无需在配置文件中硬编码：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_PERSONAL_ACCESS_TOKEN}",
        "ghcr.io/github/github-mcp-server"
      ],
      "alwaysAllow": [
        "get_pull_request"
      ]
    }
  }
}

在此示例中，${env:GITHUB_PERSONAL_ACCESS_TOKEN} 将被替换为系统环境中的 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量的值。这在以下情况下特别有用：

使用需要环境变量传递的 Docker 容器
将敏感凭据保留在配置文件之外
在具有不同凭据的不同环境中使用相同的配置

注意：环境变量必须存在于您的系统环境中才能生效。您可以通过操作系统的设置或 shell 配置文件（例如 .bashrc、.zshrc 或 Windows 环境变量）设置系统环境变量。

流式 HTTP 传输

这是通过 HTTP/HTTPS 访问远程服务器的 现代标准，提供更大的灵活性，并取代旧的 SSE 传输用于新实现。

通过单个 MCP 端点的 HTTP POST/GET 通信
可选使用 Server-Sent Events (SSE) 进行流式传输
可托管在不同机器上
支持多个客户端连接
需要网络访问
允许集中部署和管理

有关流式 HTTP 传输工作原理的更深入信息，请参阅流式 HTTP 传输。

流式 HTTP 配置参数：

type（必需）：必须设置为 "streamable-http"。
url（必需）：远程 MCP 服务器单个端点的完整 URL（例如 https://your-server.com/mcp）。
headers（可选）：包含随请求发送的自定义 HTTP 头的对象（例如用于身份验证令牌）。
alwaysAllow（可选）：从此服务器自动批准的工具名称数组。
disabled（可选）：设置为 true 以禁用此服务器配置。

流式 HTTP 配置示例：

{
  "mcpServers": {
    "modern-remote-server": {
      "type": "streamable-http",
      "url": "https://your-modern-server.com/api/mcp-endpoint",
      "headers": {
        "X-API-Key": "your-secure-api-key"
      },
      "alwaysAllow": ["newToolA", "newToolB"],
      "disabled": false
    }
  }
}

SSE 传输（旧版）

用于通过 HTTP/HTTPS 访问的旧远程服务器。对于新的远程服务器实现，建议使用流式 HTTP 传输。

通过 Server-Sent Events 协议通信（通常需要客户端到服务器和服务器到客户端的单独端点）
可托管在不同机器上
支持多个客户端连接
需要网络访问
允许集中部署和管理

有关旧 SSE 传输工作原理的更深入信息，请参阅 SSE 传输（旧版）。

SSE（旧版）配置参数：

type（可选，但建议用于清晰度）：如果为 SSE 服务器提供 url，应设置为 "sse"，以区别于流式 HTTP。如果存在 url 且省略 type，Roo Code 可能尝试推断，但显式声明更安全。
url（必需）：远程 MCP 服务器的基 URL。对于旧 SSE，这通常意味着将派生或期望单独的路径，如 /events（用于 SSE 流）和 /message（用于 POST 请求）。
headers（可选）：包含随请求发送的自定义 HTTP 头的对象（例如用于身份验证令牌）。
alwaysAllow（可选）：从此服务器自动批准的工具名称数组。
disabled（可选）：设置为 true 以禁用此服务器配置。

SSE（旧版）配置示例：

{
  "mcpServers": {
    "legacy-remote-server": {
      "type": "sse", // 显式定义为 SSE
      "url": "https://your-legacy-server-url.com/mcp-base", // 基 URL
      "headers": {
        "Authorization": "Bearer your-legacy-token"
      },
      "alwaysAllow": ["oldToolX"],
      "disabled": false
    }
  }
}

启用或禁用 MCP 服务器

在此处禁用 MCP 服务器将移除所有与 MCP 相关的逻辑和定义，减少您的令牌使用量。这将阻止 Roo Code 连接到任何 MCP 服务器，use_mcp_tool 和 access_mcp_resource 工具将不可用。如果您不打算使用 MCP 服务器，请取消选中此项。默认情况下此选项为开启状态。

点击 Roo Code 窗格顶部导航中的图标
选中/取消选中 Enable MCP Servers

启用或禁用 MCP 服务器创建

在此处禁用 MCP 服务器创建将仅从您的系统提示中移除 Roo Code 用于编写 MCP 服务器的指令，而不会移除与操作它们相关的上下文。这减少了令牌使用量。默认情况下此选项为开启状态。

点击 Roo Code 窗格顶部导航中的图标
选中/取消选中 Enable MCP Server Creation

如何使用 Roo 创建 MCP 服务器

如果您需要现有 MCP 服务器无法提供的特定工具或功能，可以要求 Roo Code 为您构建一个。

前提条件：确保在 MCP 设置面板中 启用 MCP 服务器创建 设置为开启状态。如果此设置被禁用，Roo 将没有必要的指令来构建服务器。

如何启动：

提出请求：清楚地向 Roo 请求新工具或功能。例如：
- "创建一个获取比特币当前价格的 MCP 工具。"
- "我需要一个通过其 API 连接到我公司内部用户数据库的工具。"
- "构建一个与 GitHub Gist API 交互的 MCP 服务器。"
Roo 的流程（简化）：一旦您提出请求（且设置已启用），Roo 将：
- 获取服务器创建的内部指令。
- 在默认 MCP 目录（例如 macOS 上的 ~/Documents/Cline/MCP）中创建基本服务器项目（通常是 TypeScript），除非您另有指定。
- 编写实现请求工具的代码，包括处理必要的 API 调用。
- 处理凭据：如果工具需要 API 密钥或其他凭据，Roo 将使用 ask_followup_question 工具询问您，以确保它们作为环境变量安全配置给服务器。
- 配置：自动将新服务器的配置添加到您的全局 mcp_settings.json 或项目 .roo/mcp.json 文件中。
- 激活：尝试连接到新配置的服务器，使其工具立即可用。
结果：如果成功，Roo 将确认创建，新服务器及其工具将出现在您的 MCP 服务器列表中，随时可用。

此功能允许您通过让 Roo 直接从您的请求构建特定集成来定制 Roo 的功能。有关内部机制的深入分析，请参阅工具调用机制。

管理单个 MCP 服务器

每个 MCP 服务器都有自己的配置面板，您可以在其中修改设置、管理工具并控制其操作。要访问这些设置：

点击 Roo Code 窗格顶部导航中的图标
在列表中找到要管理的 MCP 服务器

删除服务器

按下 MCP 服务器旁边的按钮
在确认框中按 Delete 按钮

重启服务器

按下要重启的 MCP 服务器旁边的按钮

启用或禁用服务器

按下 MCP 服务器旁边的切换开关以启用/禁用它

网络超时

要设置工具调用后等待 MCP 服务器响应的最大时间：

点击单个 MCP 服务器配置框底部的 Network Timeout 下拉菜单并更改时间。默认为 1 分钟，但可以在 30 秒到 5 分钟之间设置。

自动批准工具

MCP 工具自动批准按工具单独工作，默认禁用。要配置自动批准：

首先在自动批准操作中启用全局 "Use MCP servers" 自动批准选项
在 MCP 服务器设置中，找到要自动批准的特定工具
选中工具名称旁边的 Always allow 复选框

启用后，Roo Code 将自动批准此特定工具，无需提示。注意，全局 "Use MCP servers" 设置优先 - 如果它被禁用，任何 MCP 工具都不会被自动批准。

查找和安装 MCP 服务器

Roo Code 不附带任何预安装的 MCP 服务器。您需要单独查找和安装它们。

社区仓库：在 GitHub 上查找社区维护的 MCP 服务器列表
询问 Roo：您可以要求 Roo Code 帮助您查找甚至创建 MCP 服务器（当 "启用 MCP 服务器创建" 已启用时）
自行构建：使用 SDK 创建自定义 MCP 服务器，通过您自己的工具扩展 Roo Code

有关完整 SDK 文档，请访问 MCP GitHub 仓库。

在工作流中使用 MCP 工具

配置 MCP 服务器后，Roo 会自动检测其可用的工具和资源。有效利用这些工具需要了解核心交互步骤，以及 Roo 如何解释您提供的工具。

在 Roo Code 中使用 MCP

配置 MCP 服务器

编辑 MCP 设置文件

理解传输类型

STDIO 传输

在参数中使用系统环境变量

流式 HTTP 传输

SSE 传输（旧版）

启用或禁用 MCP 服务器

启用或禁用 MCP 服务器创建

如何使用 Roo 创建 MCP 服务器

管理单个 MCP 服务器

删除服务器

重启服务器

启用或禁用服务器

网络超时

自动批准工具

查找和安装 MCP 服务器

在工作流中使用 MCP 工具

核心工作流步骤

1. 启动任务

2. Roo 识别工具

配置 MCP 服务器​

编辑 MCP 设置文件​

理解传输类型​

STDIO 传输​

在参数中使用系统环境变量​

流式 HTTP 传输​

SSE 传输（旧版）​

启用或禁用 MCP 服务器​

启用或禁用 MCP 服务器创建​

如何使用 Roo 创建 MCP 服务器​

管理单个 MCP 服务器​

删除服务器​

重启服务器​

启用或禁用服务器​

网络超时​

自动批准工具​

查找和安装 MCP 服务器​

在工作流中使用 MCP 工具​

核心工作流步骤​

1. 启动任务​

2. Roo 识别工具​

配置 MCP 服务器

编辑 MCP 设置文件

理解传输类型

STDIO 传输

在参数中使用系统环境变量

流式 HTTP 传输

SSE 传输（旧版）

启用或禁用 MCP 服务器

启用或禁用 MCP 服务器创建

如何使用 Roo 创建 MCP 服务器

管理单个 MCP 服务器

删除服务器

重启服务器

启用或禁用服务器

网络超时

自动批准工具

查找和安装 MCP 服务器

在工作流中使用 MCP 工具

核心工作流步骤

1. 启动任务

2. Roo 识别工具