Roo Code 如何配置 MCP 服务器全局 mcp_settings.json 与项目 .roo/mcp.json 的优先级【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code如果你想在 Roo Code 中接入外部工具数据库、API、自定义脚本等需要把一个或多个 MCPModel Context Protocol服务器写进配置文件。Roo Code 支持两个配置层级全局的mcp_settings.json对所有 VS Code 工作区生效和项目级的.roo/mcp.json只作用于当前项目根目录下的项目。当同一个服务器名在两个文件中都出现时项目级配置优先这正是团队共享配置或按项目覆盖全局配置时的核心规则。本文基于 Using MCP in Roo Code 等文档给出从写入配置到验证连接的操作路径。准备条件Roo Code 扩展已安装并且 MCP 功能可用。项目级.roo/mcp.json支持是 Roo Code 3.112025-03-30 发布引入的见 3.11 发布说明如果你的版本更早只能使用全局配置。确认Enable MCP Servers开关已打开默认开启。该开关关闭时会移除系统提示中所有 MCP 相关逻辑use_mcp_tool和access_mcp_resource工具都不可用。在 Roo Code 面板顶部导航点击 server 图标进入 MCP 设置视图这是后续所有操作的入口。两个配置文件使用相同的 JSON 结构顶层是一个mcpServers对象其中每个键是服务器名值是该服务器的配置{ mcpServers: { server1: { command: python, args: [/path/to/server.py], env: { API_KEY: your_api_key }, alwaysAllow: [tool1, tool2], disabled: false } } }第一步写入全局 mcp_settings.json在 MCP 设置视图滚到底部点击Edit Global MCPRoo Code 会打开全局mcp_settings.json。在mcpServers对象中加入你的服务器条目并保存。本地服务器使用 STDIO 传输command必填是要执行的程序例如node、python、npx或绝对路径。macOS / Linux 下文档给出的示例以 Puppeteer 服务器为例{ mcpServers: { puppeteer: { command: npx, args: [ -y, modelcontextprotocol/server-puppeteer ] } } }Windows 下需要通过cmd执行命令对应写法{ mcpServers: { puppeteer: { command: cmd, args: [ /c, npx, -y, modelcontextprotocol/server-puppeteer ] } } }STDIO 服务器支持的可选参数args字符串参数数组、cwd启动工作目录省略时默认为第一个工作区文件夹路径或主进程工作目录、env环境变量对象、alwaysAllow自动批准的工具名数组、disabled设为true禁用该服务器、timeout每服务器超时覆盖单位秒1–3600未设置时默认 60 秒、watchPaths文件变化时自动重启服务器的监听路径、disabledTools禁用该服务器提供的某些工具。在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 ] } } }前提是该变量在系统环境中真实存在通过操作系统设置或.bashrc、.zshrc、Windows 环境变量设置。远程服务器则使用url配置此时type是必填项streamable-http新远程服务器的推荐方式或sse旧式。Roo Code 无法仅凭url推断传输类型URL 类配置省略type会直接报错。可选的headers用于携带认证头等自定义 HTTP 头。第二步写入项目级 .roo/mcp.json在同一个 MCP 设置视图底部点击Edit Project MCP。如果项目根目录还没有.roo/mcp.jsonRoo Code 会自动创建该文件。文件结构与全局文件完全相同mcpServers对象把项目专用服务器写进去即可。文档以 Context7 服务器给出项目级示例{ mcpServers: { context7: { command: npx, args: [-y, upstash/context7-mcplatest] } } }.roo/mcp.json位于项目根目录可以提交到版本控制系统方便团队共享同一份项目 MCP 配置。理解优先级同名服务器时项目级生效文档中的规则很明确全局配置作用于所有工作区除非被项目级配置覆盖如果一个服务器名同时存在于全局和项目配置中项目级配置生效project-level configuration takes precedence。这意味着一个常见的迁移/集成做法是把团队通用服务器如文档推荐的 Context7放在全局然后在某个项目里用同名条目写入.roo/mcp.json覆盖它的command、args或env。该规则在 use_mcp_tool 文档 中同样有记载Project-level servers take precedence over global servers if they share the same name.两个容易踩坑的点覆盖是按服务器名精确匹配的改名即变成并存而非覆盖需要确认服务器名在两个文件中一致。如果配置文件有 JSON 语法错误Roo Code 为避免数据丢失不会修改损坏的配置文件需要你先修复语法错误再安装或移除条目见 Marketplace 文档 的 Troubleshooting 部分。验证配置是否生效确认Enable MCP Servers开关是打开的。在 MCP 设置视图中应该能看到你写入的服务器文档以 Context7 为例服务器出现在列表中未运行时点击 activate 开关启动它。在对话中触发该服务器的工具时Roo Code 第一次会弹出批准请求批准即可继续——这同时说明连接和工具清单都已就绪。如果希望免批准先在 auto-approving-actions 设置中打开全局 Use MCP servers 自动批准选项再在具体工具的Always allow复选框上打勾。注意全局开关优先若它被禁用任何 MCP 工具都不会被自动批准。排查与限制文档列出的常见现象与对应检查项Server Not Responding确认服务器进程在运行并检查网络连通性。Permission Errors检查 API 密钥等凭据是否写进了对应层级的文件——全局服务器查mcp_settings.json项目服务器查.roo/mcp.json。Tool Not Available确认服务器确实实现了该工具且该工具没有在设置中被禁用含disabledTools列表。Slow Performance调整该 MCP 服务器的网络超时。每个服务器的配置面板底部有Network Timeout下拉框默认 60 秒可设在 1 秒到 3600 秒之间。已安装条目不工作Marketplace 文档给出的顺序检查配置文件里条目是否正确 → 重启 VS Code新配置有时需要重启→ 检查该条目的前置条件 → 查看 Roo Code output 面板的日志。几个明确的边界单个服务器可以被disabled: true整体禁用单个工具可以被disabledTools禁用这两种禁用都不会影响其他服务器。timeout只接受 1–3600 秒的范围且是每服务器的覆盖值不是全局设置。通过 Marketplace 安装 MCP 时也可以选择 Project 或 Global 作用域Roo Code 会自动写入对应文件文件不存在时会创建这与手动编辑两个文件是同一套存储位置。如果某个工具能力现有服务器都不提供可以在 MCP 设置面板打开Enable MCP Server Creation默认开启后直接让 Roo Code 生成一个新服务器它会自动把新服务器写入全局mcp_settings.json或项目.roo/mcp.json。进一步的参数说明可以查看 STDIO / Streamable HTTP / SSE 传输文档 与 推荐服务器列表。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考