MCP 服务器

添加本地和远程 MCP 工具。

你可以使用模型上下文协议（MCP）向 OpenCode 添加外部工具。OpenCode 支持本地和远程服务器。

添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。

## 注意事项#

当你使用 MCP 服务器时，它会增加上下文。如果你有很多工具，这可能会很快累积。因此我们建议谨慎选择使用哪些 MCP 服务器。

提示： MCP 服务器会增加你的上下文，所以你要谨慎选择启用哪些。

某些 MCP 服务器，如 GitHub MCP 服务器，往往会添加大量令牌，容易超出上下文限制。

# 启用#

你可以在 OpenCode 配置↗ 的 mcp 下定义 MCP 服务器。为每个 MCP 添加唯一名称。在提示 LLM 时，你可以通过名称引用该 MCP。

jsonc
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "name-of-mcp-server": {
5      // ...
6      "enabled": true
7    },
8    "name-of-other-mcp-server": {
9      // ...
10    }
11  }
12}

你也可以通过将 enabled 设置为 false 来禁用服务器。如果你想临时禁用服务器而不从配置中删除它，这很有用。

# 本地#

通过在 MCP 对象中将 type 设置为 "local" 来添加本地 MCP 服务器。

jsonc
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-local-mcp-server": {
5      "type": "local",
6      // 或 ["bun", "x", "my-mcp-command"]
7      "command": ["npx", "-y", "my-mcp-command"],
8      "enabled": true,
9      "environment": {
10        "MY_ENV_VAR": "my_env_var_value"
11      }
12    }
13  }
14}

command 是本地 MCP 服务器的启动方式。你也可以传入环境变量列表。

例如，以下是如何添加测试 @modelcontextprotocol/server-everything↗ MCP 服务器。

jsonc
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "mcp_everything": {
5      "type": "local",
6      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
7    }
8  }
9}

要使用它，我可以在提示中添加 use the mcp_everything tool。

use the mcp_everything tool to add the number 3 and 4

## 选项#

以下是配置本地 MCP 服务器的所有选项。

选项	类型	必需	描述
`type`	String	Y	MCP 服务器连接类型，必须是 `"local"`。
`command`	Array	Y	运行 MCP 服务器的命令和参数。
`environment`	Object		运行服务器时设置的环境变量。
`enabled`	Boolean		启动时启用或禁用 MCP 服务器。
`timeout`	Number		从 MCP 服务器获取工具的超时时间（毫秒）。默认 5000（5 秒）。

# 远程#

通过将 type 设置为 "remote" 来添加远程 MCP 服务器。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-remote-mcp": {
5      "type": "remote",
6      "url": "https://my-mcp-server.com",
7      "enabled": true,
8      "headers": {
9        "Authorization": "Bearer MY_API_KEY"
10      }
11    }
12  }
13}

url 是远程 MCP 服务器的 URL，使用 headers 选项可以传入请求头列表。

## 选项#

选项	类型	必需	描述
`type`	String	Y	MCP 服务器连接类型，必须是 `"remote"`。
`url`	String	Y	远程 MCP 服务器的 URL。
`enabled`	Boolean		启动时启用或禁用 MCP 服务器。
`headers`	Object		请求时发送的头信息。
`oauth`	Object		OAuth 认证配置。见下面的 OAuth 部分。
`timeout`	Number		从 MCP 服务器获取工具的超时时间（毫秒）。默认 5000（5 秒）。

# OAuth#

OpenCode 自动处理远程 MCP 服务器的 OAuth 认证。当服务器需要认证时，OpenCode 将：

检测 401 响应并启动 OAuth 流程
如果服务器支持，使用动态客户端注册（RFC 7591）
安全存储令牌以供将来请求使用

## 自动#

对于大多数支持 OAuth 的 MCP 服务器，不需要特殊配置。只需配置远程服务器：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-oauth-server": {
5      "type": "remote",
6      "url": "https://mcp.example.com/mcp"
7    }
8  }
9}

如果服务器需要认证，OpenCode 会在你首次尝试使用时提示你进行认证。如果没有，你可以使用 opencode mcp auth <server-name> 手动触发流程。

## 预注册#

如果你有来自 MCP 服务器提供商的客户端凭据，可以配置它们：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-oauth-server": {
5      "type": "remote",
6      "url": "https://mcp.example.com/mcp",
7      "oauth": {
8        "clientId": "{env:MY_MCP_CLIENT_ID}",
9        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
10        "scope": "tools:read tools:execute"
11      }
12    }
13  }
14}

## 认证#

你可以手动触发认证或管理凭据。

与特定 MCP 服务器进行认证：

bash
opencode mcp auth my-oauth-server

列出所有 MCP 服务器及其认证状态：

bash
opencode mcp list

删除存储的凭据：

bash
opencode mcp logout my-oauth-server

mcp auth 命令将打开浏览器进行授权。授权后，OpenCode 将令牌安全存储在 ~/.local/share/opencode/mcp-auth.json 中。

# 管理#

你的 MCP 作为 OpenCode 中的工具与内置工具一起可用。因此你可以像管理任何其他工具一样通过 OpenCode 配置管理它们。

## 全局#

这意味着你可以全局启用或禁用它们。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-mcp-foo": {
5      "type": "local",
6      "command": ["bun", "x", "my-mcp-command-foo"]
7    },
8    "my-mcp-bar": {
9      "type": "local",
10      "command": ["bun", "x", "my-mcp-command-bar"]
11    }
12  },
13  "tools": {
14    "my-mcp-foo": false
15  }
16}

我们也可以使用 glob 模式禁用所有匹配的 MCP。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-mcp-foo": {
5      "type": "local",
6      "command": ["bun", "x", "my-mcp-command-foo"]
7    },
8    "my-mcp-bar": {
9      "type": "local",
10      "command": ["bun", "x", "my-mcp-command-bar"]
11    }
12  },
13  "tools": {
14    "my-mcp*": false
15  }
16}

这里我们使用 glob 模式 my-mcp* 禁用所有 MCP。

## 按代理#

如果你有大量 MCP 服务器，你可能只想按代理启用它们并全局禁用。为此：

全局禁用它作为工具。
在你的代理配置中，将 MCP 服务器作为工具启用。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "my-mcp": {
5      "type": "local",
6      "command": ["bun", "x", "my-mcp-command"],
7      "enabled": true
8    }
9  },
10  "tools": {
11    "my-mcp*": false
12  },
13  "agent": {
14    "my-agent": {
15      "tools": {
16        "my-mcp*": true
17      }
18    }
19  }
20}

# 示例#

以下是一些常见 MCP 服务器的示例。如果你想记录其他服务器，可以提交 PR。

## Sentry#

添加 Sentry MCP 服务器↗ 以与你的 Sentry 项目和问题交互。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "sentry": {
5      "type": "remote",
6      "url": "https://mcp.sentry.dev/mcp",
7      "oauth": {}
8    }
9  }
10}

添加配置后，与 Sentry 进行认证：

bash
opencode mcp auth sentry

这将打开浏览器窗口完成 OAuth 流程并将 OpenCode 连接到你的 Sentry 账户。

认证后，你可以在提示中使用 Sentry 工具来查询问题、项目和错误数据。

Show me the latest unresolved issues in my project. use sentry

## Context7#

添加 Context7 MCP 服务器↗ 来搜索文档。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "context7": {
5      "type": "remote",
6      "url": "https://mcp.context7.com/mcp"
7    }
8  }
9}

在提示中添加 use context7 来使用 Context7 MCP 服务器。

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

## Grep by Vercel#

添加 Grep by Vercel↗ MCP 服务器来搜索 GitHub 上的代码片段。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "gh_grep": {
5      "type": "remote",
6      "url": "https://mcp.grep.app"
7    }
8  }
9}

由于我们将 MCP 服务器命名为 gh_grep，你可以在提示中添加 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

MCP 服务器

相关文档