Skip to content
OpenCode 中文文档
HomeDocs

MCP 服务器

添加本地和远程 MCP 工具。

您可以使用 模型上下文协议 (Model Context Protocol，简称 MCP) 向 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。

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

注意事项

使用 MCP 服务器时，它会增加上下文。如果您有很多工具，这可能会迅速累积。因此，我们建议谨慎选择启用的 MCP 服务器。

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

启用

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

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      // ...
      "enabled": true,
    },
    "name-of-other-mcp-server": {
      // ...
    },
  },
}

您还可以通过将 enabled 设置为 false 来禁用服务器。如果您想在不从配置中删除服务器的情况下临时禁用它，这非常有用。

本地服务器

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

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // 或者 ["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 服务器。

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

为了使用它，我可以在提示中加入 use the mcp_everything tool。

使用 mcp_everything 工具将数字 3 和 4 相加

选项

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

选项类型必填描述
typeString是MCP 服务器连接类型，必须为 "local"。
commandArray是运行 MCP 服务器的命令和参数。
environmentObject否运行服务器时要设置的环境变量。
enabledBoolean否启动时启用或禁用 MCP 服务器。
timeoutNumber否从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

远程服务器

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

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 服务器的 URL，您可以通过 headers 选项传入请求头列表。

选项

选项类型必填描述
typeString是MCP 服务器连接类型，必须为 "remote"。
urlString是远程 MCP 服务器的 URL。
enabledBoolean否启动时启用或禁用 MCP 服务器。
headersObject否随请求发送的 HTTP 头。
oauthObject否OAuth 身份验证配置。请参阅下面的 OAuth 部分。
timeoutNumber否从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

OAuth

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

  1. 检测到 401 响应并启动 OAuth 流程
  2. 如果服务器支持，则使用 动态客户端注册 (RFC 7591)
  3. 安全地存储 token 以备将来请求使用

自动模式

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

opencode.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 服务器提供商的客户端凭据，可以进行配置：

opencode.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 服务器进行身份验证：

Terminal window
opencode mcp auth my-oauth-server

列出所有 MCP 服务器及其身份验证状态：

Terminal window
opencode mcp list

删除存储的凭据：

Terminal window
opencode mcp logout my-oauth-server

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

禁用 OAuth

如果您想为某个服务器禁用自动 OAuth（例如，对于使用 API 密钥的服务器），请将 oauth 设置为 false：

opencode.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 选项

选项类型描述
oauthObject | falseOAuth 配置对象，或设为 false 以禁用 OAuth 自动检测。
clientIdStringOAuth 客户端 ID。如果未提供，将尝试动态客户端注册。
clientSecretStringOAuth 客户端密钥（如果授权服务器要求）。
scopeString授权期间请求的 OAuth 范围 (Scopes)。

调试

如果远程 MCP 服务器无法通过身份验证，您可以使用以下命令诊断问题：

Terminal window
# 查看所有支持 OAuth 的服务器的身份验证状态
opencode mcp auth list


# 调试特定服务器的连接和 OAuth 流程
opencode mcp debug my-oauth-server

mcp debug 命令会显示当前的身份验证状态，测试 HTTP 连通性，并尝试执行 OAuth 发现流程。

管理

您的 MCP 在 OpenCode 中作为工具可用，与内置工具并列。因此，您可以像管理其他工具一样通过 OpenCode 配置来管理它们。

全局管理

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

opencode.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。

opencode.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
  }
}

在这里，我们使用通配符模式 my-mcp* 来禁用所有 MCP。

按智能体管理

如果您有大量的 MCP 服务器，您可能希望仅按智能体启用它们，而在全局范围内禁用它们。为此：

  1. 在全局配置中将该工具禁用。
  2. 在您的 智能体配置 中，将该 MCP 服务器启用为工具。
opencode.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
      }
    }
  }
}

通配符模式

通配符模式使用简单的正则匹配规则：

  • * 匹配零个或多个任意字符（例如，"my-mcp*" 匹配 my-mcp_search、my-mcp_list 等）
  • ? 匹配恰好一个字符
  • 所有其他字符按字面意思匹配

示例

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

Sentry

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

添加配置后，向 Sentry 进行身份验证：

Terminal window
opencode mcp auth sentry

这将打开一个浏览器窗口以完成 OAuth 流程，并将 OpenCode 连接到您的 Sentry 帐户。

通过身份验证后，您可以在提示中使用 Sentry 工具来查询问题、项目和错误数据。

显示我项目中最新的未解决问题。使用 sentry

Context7

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

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

如果您注册了免费帐户，则可以使用 API 密钥并获得更高的速率限制。

opencode.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 服务器。

配置一个 Cloudflare Worker 脚本来缓存 JSON API 响应五分钟。使用 context7

或者，您可以将类似以下内容添加到您的 AGENTS.md。

AGENTS.md
当您需要搜索文档时，请使用 `context7` 工具。

Grep by Vercel

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

opencode.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 以让智能体使用它。

在 SST Astro 组件中设置自定义域名的正确方法是什么？使用 gh_grep 工具

或者，您可以将类似以下内容添加到您的 AGENTS.md。

AGENTS.md
如果您不确定如何执行某项操作，请使用 `gh_grep` 从 GitHub 搜索代码示例。