定制与扩展

MCP 服务器

添加本地和远程 MCP 工具。

官方简体中文源 / mcp-servers.mdx / 固定提交 8c81f9a4

你可以通过 _Model Context Protocol_（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。

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

注意事项

使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器。

某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。

启用

你可以在 OpenCode 配置的 mcp 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。

jsonc
{
  "$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
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

本地配置值会覆盖远程默认值。详情请参阅配置优先级。

本地

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

jsonc
{
  "$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 MCP 服务器的方法。

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
    },
  },
}

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

txt
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
{
  "$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 部分。
timeout 数字 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。

OAuth

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

  1. 检测 401 响应并启动 OAuth 流程
  2. 在服务器支持的情况下使用动态客户端注册（RFC 7591）
  3. 安全地存储 Token 以供后续请求使用

自动认证

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

json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

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

预注册

如果你已经从 MCP 服务器提供商处获得了客户端凭据，可以直接配置：

json
{
  "$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
{
  "$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
{
  "$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
{
  "$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. 在代理配置中，将 MCP 服务器作为工具启用。
json
{
  "$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 等）
  • ? 匹配恰好一个字符
  • 其他字符按字面值匹配

示例

以下是一些常见 MCP 服务器的配置示例。如果你想记录其他服务器的用法，欢迎提交 PR。

Sentry

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

json
{
  "$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
Show me the latest unresolved issues in my project. use sentry

Context7

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

json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

如果你注册了免费账户，可以使用 API 密钥来获得更高的速率限制。

json
{
  "$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
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

你也可以在 AGENTS.md 中添加类似的规则。

md
When you need to search docs, use `context7` tools.

Grep by Vercel

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

json
{
  "$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
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

你也可以在 AGENTS.md 中添加类似的规则。

md
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.

官方原文

本页来自 OpenCode 官方简体中文文档的固定版本，并转换为 xueai 静态页面。内容以官方持续更新的页面为准。

内容授权与修改

官方文档源代码采用 MIT License。本站保留许可证、固定提交号和修改说明，不代表 OpenCode 或 anomalyco 对本站背书。

MIT License，来源和修改说明