--- title: MCP 服务器 description: 添加本地和远程 MCP 工具。 --- 你可以通过 _Model Context Protocol_（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。 添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。 --- #### 注意事项 使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器。 :::tip MCP 服务器会占用你的上下文空间，所以请谨慎选择启用哪些服务器。 ::: 某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。 --- ## 启用 你可以在 [OpenCode 配置](https://opencode.ai/docs/config/)的 `mcp` 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。 ```jsonc title="opencode.jsonc" {6} { "$schema": "https://opencode.ai/config.json", "mcp": { "name-of-mcp-server": { // ... "enabled": true, }, "name-of-other-mcp-server": { // ... }, }, } ``` 你也可以将 `enabled` 设置为 `false` 来禁用某个服务器。当你想临时禁用某个服务器而不将其从配置中移除时，这个选项非常有用。 --- ### 覆盖远程默认值 组织可以通过其 `.well-known/opencode` 端点提供默认的 MCP 服务器。这些服务器可能默认处于禁用状态，允许用户按需启用。 要启用组织远程配置中的某个服务器，请在本地配置中添加该服务器并设置 `enabled: true`： ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": true } } } ``` 本地配置值会覆盖远程默认值。详情请参阅[配置优先级](/docs/config#precedence-order)。 --- ## 本地 通过在 MCP 对象中将 `type` 设置为 `"local"` 来添加本地 MCP 服务器。 ```jsonc title="opencode.jsonc" {15} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-local-mcp-server": { "type": "local", // Or ["bun", "x", "my-mcp-command"] "command": ["npx", "-y", "my-mcp-command"], "enabled": true, "environment": { "MY_ENV_VAR": "my_env_var_value", }, }, }, } ``` `command` 用于指定本地 MCP 服务器的启动命令。你还可以传入一组环境变量。 例如，以下是添加测试用的 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 服务器的方法。 ```jsonc title="opencode.jsonc" { "$schema": "https://opencode.ai/config.json", "mcp": { "mcp_everything": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], }, }, } ``` 要使用它，可以在提示词中添加 `use the mcp_everything tool`。 ```txt "mcp_everything" use the mcp_everything tool to add the number 3 and 4 ``` --- #### 选项 以下是配置本地 MCP 服务器的所有选项。 | 选项 | 类型 | 必填 | 描述 | | ------------- | ------ | ---- | ----------------------------------------------------------------- | | `type` | 字符串 | 是 | MCP 服务器连接类型，必须为 `"local"`。 | | `command` | 数组 | 是 | 运行 MCP 服务器的命令及参数。 | | `environment` | 对象 | | 运行服务器时设置的环境变量。 | | `enabled` | 布尔值 | | 启动时启用或禁用该 MCP 服务器。 | | `timeout` | 数字 | | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 | --- ## 远程 通过将 `type` 设置为 `"remote"` 来添加远程 MCP 服务器。 ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "my-remote-mcp": { "type": "remote", "url": "https://my-mcp-server.com", "enabled": true, "headers": { "Authorization": "Bearer MY_API_KEY" } } } } ``` `url` 是远程 MCP 服务器的地址，通过 `headers` 选项可以传入一组请求头。 --- #### 选项 | 选项 | 类型 | 必填 | 描述 | | --------- | ------ | ---- | ----------------------------------------------------------------- | | `type` | 字符串 | 是 | MCP 服务器连接类型，必须为 `"remote"`。 | | `url` | 字符串 | 是 | 远程 MCP 服务器的 URL。 | | `enabled` | 布尔值 | | 启动时启用或禁用该 MCP 服务器。 | | `headers` | 对象 | | 随请求发送的请求头。 | | `oauth` | 对象 | | OAuth 身份验证配置。详见下方 [OAuth](#oauth) 部分。 | | `timeout` | 数字 | | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 | --- ## OAuth OpenCode 会自动处理远程 MCP 服务器的 OAuth 身份验证。当服务器需要身份验证时，OpenCode 将： 1. 检测 401 响应并启动 OAuth 流程 2. 在服务器支持的情况下使用**动态客户端注册（RFC 7591）** 3. 安全地存储 Token 以供后续请求使用 --- ### 自动认证 对于大多数支持 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器即可： ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp" } } } ``` 如果服务器需要身份验证，OpenCode 会在你首次使用时提示你进行认证。你也可以使用 `opencode mcp auth ` [手动触发认证流程](#authenticating)。 --- ### 预注册 如果你已经从 MCP 服务器提供商处获得了客户端凭据，可以直接配置： ```json title="opencode.json" {7-11} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": { "clientId": "{env:MY_MCP_CLIENT_ID}", "clientSecret": "{env:MY_MCP_CLIENT_SECRET}", "scope": "tools:read tools:execute" } } } } ``` --- ### 身份验证 你可以手动触发身份验证或管理凭据。 对特定 MCP 服务器进行身份验证： ```bash opencode mcp auth my-oauth-server ``` 列出所有 MCP 服务器及其认证状态： ```bash opencode mcp list ``` 删除已存储的凭据： ```bash opencode mcp logout my-oauth-server ``` `mcp auth` 命令会打开浏览器进行授权。授权完成后，OpenCode 会将 Token 安全地存储在 `~/.local/share/opencode/mcp-auth.json` 中。 --- #### 禁用 OAuth 如果你想为某个服务器禁用自动 OAuth（例如，该服务器使用 API 密钥而非 OAuth），可以将 `oauth` 设置为 `false`： ```json title="opencode.json" {7} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-api-key-server": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:MY_API_KEY}" } } } } ``` --- #### OAuth 选项 | 选项 | 类型 | 描述 | | -------------- | --------------- | ------------------------------------------------------ | | `oauth` | 对象 \| `false` | OAuth 配置对象，或设为 `false` 以禁用 OAuth 自动检测。 | | `clientId` | 字符串 | OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。 | | `clientSecret` | 字符串 | OAuth 客户端密钥（如果授权服务器要求提供）。 | | `scope` | 字符串 | 授权时请求的 OAuth 作用域。 | #### 调试 如果远程 MCP 服务器身份验证失败，你可以通过以下方式诊断问题： ```bash # 查看所有支持 OAuth 的服务器的认证状态 opencode mcp auth list # 调试特定服务器的连接和 OAuth 流程 opencode mcp debug my-oauth-server ``` `mcp debug` 命令会显示当前认证状态、测试 HTTP 连接，并尝试执行 OAuth 发现流程。 --- ## 管理 你的 MCP 在 OpenCode 中作为工具使用，与内置工具并列。因此，你可以像管理其他工具一样，通过 OpenCode 配置来管理它们。 --- ### 全局 你可以全局启用或禁用 MCP 工具。 ```json title="opencode.json" {14} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] }, "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] } }, "tools": { "my-mcp-foo": false } } ``` 也可以使用 glob 模式来禁用所有匹配的 MCP。 ```json title="opencode.json" {14} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] }, "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] } }, "tools": { "my-mcp*": false } } ``` 这里使用 glob 模式 `my-mcp*` 来禁用所有 MCP。 --- ### 按代理配置 如果你有大量 MCP 服务器，可以选择全局禁用它们，然后仅在特定代理中启用。具体做法： 1. 全局禁用该工具。 2. 在[代理配置](/docs/agents#tools)中，将 MCP 服务器作为工具启用。 ```json title="opencode.json" {11, 14-18} { "$schema": "https://opencode.ai/config.json", "mcp": { "my-mcp": { "type": "local", "command": ["bun", "x", "my-mcp-command"], "enabled": true } }, "tools": { "my-mcp*": false }, "agent": { "my-agent": { "tools": { "my-mcp*": true } } } } ``` --- #### Glob 模式 glob 模式使用简单的正则通配符规则： - `*` 匹配零个或多个任意字符（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等） - `?` 匹配恰好一个字符 - 其他字符按字面值匹配 :::note MCP 服务器工具在注册时以服务器名称作为前缀，因此要禁用某个服务器的所有工具，只需使用： ``` "mymcpservername_*": false ``` ::: --- ## 示例 以下是一些常见 MCP 服务器的配置示例。如果你想记录其他服务器的用法，欢迎提交 PR。 --- ### Sentry 添加 [Sentry MCP 服务器](https://mcp.sentry.dev) 以与你的 Sentry 项目和问题进行交互。 ```json title="opencode.json" {4-8} { "$schema": "https://opencode.ai/config.json", "mcp": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} } } } ``` 添加配置后，使用 Sentry 进行身份验证： ```bash opencode mcp auth sentry ``` 这会打开浏览器窗口完成 OAuth 流程，将 OpenCode 连接到你的 Sentry 账户。 认证完成后，你可以在提示词中使用 Sentry 工具来查询问题、项目和错误数据。 ```txt "use sentry" Show me the latest unresolved issues in my project. use sentry ``` --- ### Context7 添加 [Context7 MCP 服务器](https://github.com/upstash/context7) 以搜索文档。 ```json title="opencode.json" {4-7} { "$schema": "https://opencode.ai/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" } } } ``` 如果你注册了免费账户，可以使用 API 密钥来获得更高的速率限制。 ```json title="opencode.json" {7-9} { "$schema": "https://opencode.ai/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" } } } } ``` 这里假设你已经设置了 `CONTEXT7_API_KEY` 环境变量。 在提示词中添加 `use context7` 即可使用 Context7 MCP 服务器。 ```txt "use context7" Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7 ``` 你也可以在 [AGENTS.md](/docs/rules/) 中添加类似的规则。 ```md title="AGENTS.md" When you need to search docs, use `context7` tools. ``` --- ### Grep by Vercel 添加 [Grep by Vercel](https://grep.app) MCP 服务器以搜索 GitHub 上的代码片段。 ```json title="opencode.json" {4-7} { "$schema": "https://opencode.ai/config.json", "mcp": { "gh_grep": { "type": "remote", "url": "https://mcp.grep.app" } } } ``` 由于我们将 MCP 服务器命名为 `gh_grep`，你可以在提示词中添加 `use the gh_grep tool` 来让代理使用它。 ```txt "use the gh_grep tool" What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool ``` 你也可以在 [AGENTS.md](/docs/rules/) 中添加类似的规则。 ```md title="AGENTS.md" If you are unsure how to do something, use `gh_grep` to search code examples from GitHub. ```