在 Roo Code 中使用 MCP

了解如何在 Roo Code 中使用模型上下文协议 (MCP) 的完整指南。学习如何配置 MCP 服务器、管理工具以及扩展 Roo Code 的功能。

对 MCP 服务器感到困惑？
MCP（模型上下文协议）服务器充当一座桥梁，让 Roo Code 能够访问更广泛的工具和外部服务，如数据库、API 或自定义脚本。它使用一种标准的通信方法，允许 Roo 利用这些外部能力。
要深入了解，请查看什么是 MCP？。

模型上下文协议 (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 设置视图的底部。
点击相应的按钮：

编辑全局 MCP： 打开全局 mcp_settings.json 文件。
编辑项目 MCP： 打开项目特定的 .roo/mcp.json 文件。如果此文件不存在，Roo Code 将为你创建它。

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

Roo Code 中 MCP 服务器配置示例 (STDIO 传输)

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

了解传输类型

MCP 支持三种传输类型用于服务器通信：本地服务器的 STDIO、可流式 HTTP（推荐用于新的远程服务器）和 SSE（用于传统远程服务器）。

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", // Optional: Specify working directory
      "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 传输。

通过 HTTP POST/GET 与单个 MCP 端点通信。
可选择使用服务器发送事件 (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 传输。

通过服务器发送事件协议进行通信（通常需要单独的端点用于客户端到服务器和服务器到客户端的通信）。
可以在另一台机器上托管。
支持多个客户端连接。
需要网络访问。
允许集中部署和管理。

有关传统 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", // Explicitly define as SSE
      "url": "https://your-legacy-server-url.com/mcp-base", // 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 面板顶部导航栏中的 ⚙️ 图标。
勾选/取消勾选 “启用 MCP 服务器”。

启用或禁用 MCP 服务器创建

在此处禁用你的 MCP 服务器创建将只从 Roo Code 用于编写 MCP 服务器的系统提示中移除指令，而不会移除与操作它们相关的上下文。这会减少令牌使用。此功能默认启用。

点击 Roo Code 面板顶部导航栏中的 ⚙️ 图标。
勾选/取消勾选 “启用 MCP 服务器创建”。

如何使用 Roo 创建 MCP 服务器

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

先决条件： 确保在 MCP 设置面板中勾选了启用 MCP 服务器创建设置。如果此功能被禁用，Roo 将没有必要的指令来构建服务器。

如何启动：

提出请求： 清楚地向 Roo 提出新工具或功能的需求。例如：

“创建一个获取比特币当前价格的 MCP 工具。”
“我需要一个工具，通过 API 连接到我公司的内部用户数据库。”
“构建一个 MCP 服务器来与 GitHub Gist API 交互。”

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 服务器旁边的 trash。
在确认框上按删除按钮。

重启服务器

点击要重启的 MCP 服务器旁边的 restart 按钮。

启用或禁用服务器

点击 MCP 服务器旁边的 toggle 开关以启用/禁用它。

网络超时

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

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

自动批准工具

MCP 工具自动批准是按工具进行的，默认禁用。要配置自动批准：

首先在 自动批准操作 中启用全局使用 MCP 服务器自动批准选项。
在 MCP 服务器设置中，找到你想要自动批准的特定工具。
勾选工具名称旁边的 “总是允许” 复选框。

启用后，Roo Code 将自动批准此特定工具，无需提示。请注意，全局 “使用 MCP 服务器” 设置优先——如果它被禁用，则不会自动批准任何 MCP 工具。

查找和安装 MCP 服务器

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

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

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

在你的工作流程中使用 MCP 工具

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

核心工作流程步骤

你与 MCP 工具的交互通常遵循此顺序：

1. 启动任务

首先在 Roo Code 聊天界面中输入你的请求。

2. Roo 的工具识别

Roo 分析你的请求，以确定是否有可用的 MCP 工具可以提供帮助。此阶段高度依赖于你的 MCP 工具定义的质量。

描述的关键作用

Roo 的能力：

识别适合任务的正确工具，
理解如何构建必要的参数，以及
避免误解工具的能力，所有这些都取决于工具本身及其参数的清晰、简洁和信息丰富的描述。模糊或缺失的信息，尤其是参数，会严重阻碍 Roo 有效选择或使用工具的能力。

例如，一个像“分析我的 API 的性能”这样的请求可能会导致 Roo 考虑一个专为 API 端点测试设计的 MCP 工具。Roo 是否成功识别并按预期使用此工具，直接受到其描述质量的影响。

定义 MCP 工具的最佳实践

为了确保 Roo 能够高效地利用你的 MCP 工具，请在定义它们时考虑以下事项：

工具名称： 选择一个描述性和明确的名称，清楚地表明工具的主要功能。
工具描述： 提供一个关于工具作用、目的以及使用它的任何重要上下文或先决条件的全面摘要。解释使用工具的结果。
参数描述： 这至关重要。对于每个参数：
- 清楚地说明其目的和期望的数据类型（例如，“用于查找的用户 ID”、“要处理的文件路径”、“搜索查询字符串”）。
- 指定任何格式要求、约束，或在适用时提供有效值的示例。
- 指示参数是可选还是必需（尽管 MCP 模式通常会处理此问题，但一个注释可能会有所帮助）。
对 AI 的清晰度： 编写描述时，就好像你在向另一位开发者（或 AI）解释工具一样。Roo 拥有的上下文越多，它就越能将工具集成到其解决问题的工作流程中。如果一个工具旨在以特定顺序或与其他工具结合使用，提及这一点也会有所帮助。
使用自定义指令进行增强： 除了嵌入在 MCP 服务器中的描述之外，你还可以通过提供自定义指令来进一步指导 Roo 使用特定的 MCP 工具。这使你能够定义首选方法、概述涉及多个工具的复杂工作流程，或指定何时应优先使用或避免使用特定 MCP 工具。

3. 工具调用

如果 Roo 在工具描述的指导下，识别出合适的工具，它将提议使用该工具。然后，你批准此操作（除非为受信任的工具配置了自动批准）。

通过 MCP 服务器实现协同效应最大化

通过投入精力来精心编写详细的描述，并可能使用自定义指令对其进行增强，你将显著提高 Roo Code 和你的 MCP 服务器之间的协同作用。这释放了它们在更可靠和高效地完成任务方面的全部潜力。

故障排除 MCP 服务器

常见问题和解决方案：

服务器无响应： 检查服务器进程是否正在运行并验证网络连接。
权限错误： 确保在你的 mcp_settings.json（用于全局设置）或 .roo/mcp.json（用于项目设置）中配置了正确的 API 密钥和凭据。
工具不可用： 确认服务器正确实现了该工具，并且该工具在设置中未被禁用。
性能缓慢： 尝试调整特定 MCP 服务器的网络超时值。

平台特定 MCP 配置示例

Windows 配置示例

在 Windows 上设置 MCP 服务器时，你需要使用 Windows 命令提示符（cmd）来执行命令。以下是在 Windows 上配置 Puppeteer MCP 服务器的示例：

{
  "mcpServers": {
    "puppeteer": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

这个特定于 Windows 的配置：

使用 cmd 命令访问 Windows 命令提示符。
使用 /c 告诉 cmd 执行命令然后终止。
使用 npx 来运行包，而无需永久安装它。
-y 标志自动回答安装过程中的任何提示“是”。
运行 @modelcontextprotocol/server-puppeteer 包，该包提供浏览器自动化功能。

macOS 和 Linux 配置示例

在 macOS 或 Linux 上设置 MCP 服务器时，你可以使用更简单的配置，因为你不需要 Windows 命令提示符。以下是在 macOS 或 Linux 上配置 Puppeteer MCP 服务器的示例：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

此配置：

直接使用 npx，无需 shell 封装器。
使用 -y 标志自动回答安装过程中的任何提示“是”。
运行 @modelcontextprotocol/server-puppeteer 包，该包提供浏览器自动化功能。

同样的方法可用于 Windows 上的其他 MCP 服务器，根据需要调整包名以适应不同服务器类型。

运行时版本管理器配置

当处理不同版本的编程语言或运行时时，你可能会使用像 asdf 或 mise（以前称为 rtx）这样的版本管理器。这些工具帮助在单个系统上管理多个运行时版本。以下是如何配置 MCP 服务器以与这些版本管理器协同工作：

mise 配置示例

mise 是一个快速、现代的运行时版本管理器，可用于指定你的 MCP 服务器要使用的 Node.js、Python 或其他运行时的版本：

{
  "mcpServers": {
    "mcp-batchit": {
      "command": "mise",
      "args": [
        "x",
        "--",
        "node",
        "/Users/myself/workspace/mcp-batchit/build/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "search",
        "batch_execute"
      ]
    }
  }
}

此配置：

使用 mise 命令来管理运行时版本。
x 子命令使用配置的运行时版本执行命令。
-- 将 mise 参数与要运行的命令分隔开来。
运行你的 mise 设置中配置的特定版本的 node。
指向 MCP 服务器的 JavaScript 文件。
自动允许“search”和“batch_execute”工具。

asdf 配置示例

asdf 是一个用于管理多个运行时版本的流行工具。以下是如何配置 MCP 服务器以使用由 asdf 管理的特定 Node.js 版本的示例：

{
  "mcpServers": {
    "appsignal": {
      "command": "/Users/myself/.asdf/installs/nodejs/22.2.0/bin/node",
      "args": [
        "/Users/myself/Code/Personal/my-mcp/build/index.js"
      ],
      "env": {
        "ASDF_NODE_VERSION": "22.2.0"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

此配置：

直接引用 asdf 安装目录中的 Node.js 可执行文件。
设置 ASDF_NODE_VERSION 环境变量以确保版本使用的一致性。
指向 MCP 服务器的 JavaScript 文件。

使用版本管理器可确保你的 MCP 服务器使用正确的运行时版本运行，无论系统的默认版本是什么，从而在不同环境中提供一致性并防止版本冲突。

模型上下文协议 (MCP)

了解 Roo Code 中的模型上下文协议 (MCP)。发现如何使用自定义工具、资源和服务器集成来扩展 AI 功能。

MCP是什么?

模型上下文协议（MCP）是用于大型语言模型（LLM）系统与外部工具和服务交互的标准化通信协议。它充当 AI 助手和各种数据源或应用程序之间的通用适配器。