OpenCode MCP 服务器

清夏晚风 Lv7
  2026-07-20 19:11:03 2026-07-20 19:11:03 Created   2026-09-24 06:18:38 2026-09-24 06:18:38 Updated      

概述

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

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

注意事项：MCP 服务器会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。因此，建议谨慎选择要启用的 MCP 服务器。

启用

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

1
2
3
4
5
6
7
8
9
10
11
12
{
  "$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：

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

本地配置值会覆盖远程默认值。

本地

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

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

command 用于指定本地 MCP 服务器的启动命令，还可以传入一组环境变量。

例如，添加测试用的 @modelcontextprotocol/server-everything MCP 服务器：

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

使用时，在提示词中添加 use the mcp_everything tool：

1
use the mcp_everything tool to add the number 3 and 4

选项

选项 类型 必填 描述
type 字符串 是 MCP 服务器连接类型，必须为 "local"。
command 数组 是 运行 MCP 服务器的命令及参数。
environment 对象 运行服务器时设置的环境变量。
enabled 布尔值 启动时启用或禁用该 MCP 服务器。
timeout 数字 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。

远程

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

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "$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 服务器，无需特殊配置，只需配置远程服务器即可：

1
2
3
4
5
6
7
8
9
{
  "$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 服务器提供商处获得了客户端凭据，可以直接配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "$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 服务器进行身份验证：

1
opencode mcp auth my-oauth-server

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

1
opencode mcp list

删除已存储的凭据：

1
opencode mcp logout my-oauth-server

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

禁用 OAuth

如果你想为某个服务器禁用自动 OAuth（例如，该服务器使用 API 密钥而非 OAuth），可以将 oauth 设置为 false：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "$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 服务器身份验证失败，你可以通过以下方式诊断问题：

1
2
3
4
5
# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list

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

mcp debug 命令会显示当前认证状态、测试 HTTP 连接，并尝试执行 OAuth 发现流程。

管理

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

全局

你可以全局启用或禁用 MCP 工具：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "$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：

1
2
3
4
5
6
7
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": { /* ... */ },
  "tools": {
    "my-mcp*": false
  }
}

按代理配置

如果你有大量 MCP 服务器，可以选择全局禁用它们，然后仅在特定代理中启用：

  1. 全局禁用该工具。
  2. 在代理配置中，将 MCP 服务器作为工具启用。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "$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 模式规则

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

MCP 服务器工具在注册时以服务器名称作为前缀，因此要禁用某个服务器的所有工具，使用 "mymcpservername_*": false。

示例

Sentry

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

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

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

1
opencode mcp auth sentry

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

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

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

Context7

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

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

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

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

在提示词中添加 use context7 即可使用：

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

也可以在 AGENTS.md 中添加规则：

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

Grep by Vercel

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

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

由于将 MCP 服务器命名为 gh_grep，可以在提示词中添加 use the gh_grep tool 来让代理使用它：

1
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

也可以在 AGENTS.md 中添加规则：

1
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
  • Title: OpenCode MCP 服务器
  • Author: 清夏晚风
  • Created at : 2026-07-20 19:11:03
  • Updated at : 2026-09-24 06:18:38
  • Link: https://blog.yuil.cn/2026/07/20/OpenCode MCP 服务器/
  • License: This work is licensed under CC BY-NC-SA 4.0.
Comments
On this page
OpenCode MCP 服务器
  1. 概述
  2. 启用
    1. 覆盖远程默认值
  3. 本地
    1. 选项
  4. 远程
    1. 选项
  5. OAuth
    1. 自动认证
    2. 预注册
    3. 身份验证
    4. 禁用 OAuth
    5. OAuth 选项
    6. 调试
  6. 管理
    1. 全局
    2. 按代理配置
    3. Glob 模式规则
  7. 示例
    1. Sentry
    2. Context7
    3. Grep by Vercel