OpenCode MCP 服务器配置

MCP（Model Context Protocol，模型上下文协议）是一种开放协议，允许你为 OpenCode 接入外部工具和数据源。添加 MCP 服务器后，其提供的工具会自动与 OpenCode 的内置工具并列，LLM 可以在对话中直接调用它们。

OpenCode 同时支持两种 MCP 服务器：

  • 本地（local）：在你的机器上通过命令行启动的 MCP 进程，适合本地工具和脚本
  • 远程（remote）：通过 HTTPS 连接的远端 MCP 服务，适合云端服务和第三方平台

上下文消耗提醒：每个 MCP 服务器都会占用对话的上下文空间。启用的工具越多，每次对话消耗的 Token 越多，越容易触达模型的上下文上限。建议只启用当前任务实际需要的 MCP 服务器，用完即关。某些服务器（如 GitHub MCP）工具数量众多，Token 消耗尤其显著，使用时请格外注意。

基础配置结构

所有 MCP 服务器配置写在 opencode.json 的 mcp 字段下。每个服务器需要一个唯一的名称作为键名，该名称也可以在提示词中用来指定调用哪个 MCP：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {         // 服务器名称（自定义，全局唯一）
      "type": "local",         // 连接类型：local 或 remote
      // ...其他配置项
      "enabled": true          // 是否启用，默认为 true
    },
    "another-mcp-server": {    // 可同时配置多个 MCP 服务器
      "type": "remote",
      // ...
    }
  }
}

将 enabled 设置为 false 可以临时禁用某个服务器，而无需将其从配置文件中删除，方便按需开关：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": false          // 暂时禁用，配置保留，下次需要时改回 true 即可
    }
  }
}

本地 MCP 服务器

本地 MCP 服务器通过在你的机器上运行一个命令进程来提供工具。将 type 设置为 "local"，并通过 command 指定启动命令：

实例

{
  "$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"
      }
    }
  }
}

本地服务器配置项

配置项 类型 必填 说明
type 字符串 是 连接类型，本地服务器必须填写 "local"
command 数组 是 启动 MCP 服务器的命令及参数，数组形式，如 ["npx", "-y", "my-mcp"]
environment 对象 否 运行服务器时注入的环境变量，键值对形式
enabled 布尔值 否 是否在启动时启用该服务器，默认为 true
timeout 数字 否 从 MCP 服务器获取工具列表的超时时间（毫秒），默认为 5000（5 秒）

示例：添加测试用 MCP 服务器

以下是添加官方测试用 MCP 服务器 @modelcontextprotocol/server-everything 的示例，可用于验证 MCP 功能是否正常工作：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      // npx -y 表示自动确认安装，无需手动 npm install
    }
  }
}

配置完成后，在提示词中加入服务器名称，即可让 LLM 调用该 MCP 的工具：

use the mcp_everything tool to add the number 3 and 4

远程 MCP 服务器

远程 MCP 服务器通过 HTTPS 连接到云端服务。将 type 设置为 "remote"，并通过 url 指定服务器地址：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",                               // 连接类型：远程
      "url": "https://my-mcp-server.com",             // 远程服务器地址（必填）
      "enabled": true,
      "headers": {                                    // 随请求发送的 HTTP 请求头（可选）
        "Authorization": "Bearer MY_API_KEY"          // 常用于 API 密钥认证
      }
    }
  }
}

远程服务器配置项

配置项 类型 必填 说明
type 字符串 是 连接类型，远程服务器必须填写 "remote"
url 字符串 是 远程 MCP 服务器的完整 HTTPS 地址
enabled 布尔值 否 是否在启动时启用该服务器，默认为 true
headers 对象 否 随每次请求发送的 HTTP 请求头，常用于 API 密钥认证
oauth 对象 / false 否 OAuth 身份验证配置，或设为 false 禁用自动 OAuth 检测
timeout 数字 否 从 MCP 服务器获取工具列表的超时时间（毫秒），默认为 5000（5 秒）

引用环境变量

在配置文件中，不应将 API 密钥等敏感信息直接写成明文。OpenCode 支持通过 {env:变量名} 语法在运行时读取系统环境变量：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"    // 运行时自动读取环境变量 MY_API_KEY 的值
                                                      // 需要提前在系统中设置该环境变量：
                                                      // export MY_API_KEY=your_actual_key
      }
    }
  }
}

OAuth 身份验证

OpenCode 内置了对远程 MCP 服务器的 OAuth 身份验证支持，整个流程几乎全自动，无需手动处理 Token。

自动认证流程

当服务器需要 OAuth 认证时，OpenCode 会自动完成以下步骤：

  1. 检测到服务器返回 401（未授权）响应
  2. 自动启动 OAuth 授权流程，打开浏览器引导你完成登录
  3. 在服务器支持的情况下，使用动态客户端注册（RFC 7591）自动注册应用
  4. 将获取到的 Token 安全存储在 ~/.local/share/opencode/mcp-auth.json 中
  5. 后续请求自动携带 Token，无需重复登录

1、自动 OAuth（无需额外配置）

对于大多数支持 OAuth 的 MCP 服务器，只需配置 url 即可，OpenCode 会在首次使用时自动引导你完成认证：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
      // 无需任何额外配置，OpenCode 自动处理 OAuth 流程
    }
  }
}

也可以手动触发认证流程（例如 Token 过期后重新登录）：

opencode mcp auth my-oauth-server

2、预注册客户端凭据

如果你已经从服务提供商处拿到了固定的客户端 ID 和密钥，可以直接在配置中指定，跳过动态注册步骤：

实例

{
  "$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"             // 请求的权限范围，具体值由服务提供商规定
      }
    }
  }
}

3、禁用 OAuth（使用 API 密钥认证）

如果服务器使用 API 密钥而非 OAuth 认证，可以将 oauth 设为 false 禁用自动 OAuth 检测，改用 headers 传递密钥：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,                                   // 禁用 OAuth 自动检测
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"     // 直接用 API 密钥认证
      }
    }
  }
}

OAuth 配置项

配置项 类型 说明
oauth 对象 / false OAuth 配置对象；设为 false 可完全禁用 OAuth 自动检测
clientId 字符串 OAuth 客户端 ID。若未提供，OpenCode 将尝试动态客户端注册
clientSecret 字符串 OAuth 客户端密钥（如果授权服务器要求提供）
scope 字符串 授权时请求的权限范围，多个权限用空格分隔，具体值由服务提供商规定

认证管理命令

OpenCode 提供了一组命令行工具用于管理 MCP 的认证状态：

# 对指定 MCP 服务器进行身份验证（会打开浏览器完成 OAuth 授权）
opencode mcp auth my-oauth-server

# 列出所有已配置的 MCP 服务器及其当前认证状态
opencode mcp list

# 删除指定服务器已存储的凭据（下次使用时需要重新登录）
opencode mcp logout my-oauth-server

# 调试指定服务器的连接和 OAuth 流程（显示认证状态、测试连接、执行 OAuth 发现流程）
opencode mcp debug my-oauth-server

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

覆盖远程默认配置

组织可以通过 .well-known/opencode 端点为成员提供预置的 MCP 服务器配置，这些服务器可能默认处于禁用状态。如果你需要启用其中某个服务器，在本地配置中添加同名条目并设置 enabled: true 即可，本地配置会覆盖远程默认值：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {                                         // 与组织远程配置中的服务器名称一致
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true                                 // 本地设为 true，覆盖远程的默认禁用状态
    }
  }
}

工具管理

MCP 服务器注册后，其工具会以 服务器名称_工具名称 的形式出现在 OpenCode 的工具列表中，可以通过 tools 字段进行统一管理。

1、全局禁用指定 MCP 的工具

实例

{
  "$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    // 禁用 my-mcp-foo 服务器的所有工具（服务器仍会启动，但工具不可用）
  }
}

2、使用 Glob 模式批量禁用

使用 Glob 通配符可以一次性匹配并禁用多个 MCP 服务器的工具：

实例

{
  "$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 开头的服务器的工具
  }
}

3、按代理启用特定 MCP 工具

如果你配置了大量 MCP 服务器，但每个代理只需要其中一部分，可以先全局禁用所有 MCP 工具，再在特定代理的配置中按需启用。这样可以精确控制每个代理能访问哪些工具，避免上下文浪费：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true         // 服务器本身保持启动状态（否则代理也无法使用）
    }
  },
  "tools": {
    "my-mcp*": false          // 第一步：全局禁用该 MCP 的所有工具，默认对话中不可用
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true       // 第二步：仅在 my-agent 代理中启用，其他代理不受影响
      }
    }
  }
}

Glob 模式规则

通配符 含义 示例
* 匹配零个或多个任意字符 my-mcp* 匹配 my-mcp_search、my-mcp_list 等
? 精确匹配一个任意字符 my-mcp? 匹配 my-mcpA，但不匹配 my-mcpAB
其他字符 按字面值精确匹配 my-mcp-foo 只匹配名称完全相同的服务器

MCP 服务器的工具在注册时会以服务器名称作为前缀，例如服务器 myserver 的工具会注册为 myserver_toolname。因此，要禁用某个服务器的所有工具，使用 "myserver_*": false 即可精确匹配。

配置示例

Sentry

添加 Sentry MCP 服务器，可以在对话中直接查询 Sentry 项目的错误、问题和事件数据：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}      // 空对象表示启用 OAuth 自动认证，OpenCode 会自动处理整个 OAuth 流程
    }
  }
}

添加配置后，执行以下命令完成账号授权（会打开浏览器进行 OAuth 登录）：

opencode mcp auth sentry

认证完成后，在提示词中加入 use sentry 即可调用 Sentry 工具：

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

Context7

添加 Context7 MCP 服务器，可以在对话中搜索各类技术文档，帮助 LLM 获取最新准确的 API 参考：

实例

// 基础版（无速率限制优化）
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

实例

// 注册免费账户后，使用 API 密钥可获得更高的速率限制
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"    // 从环境变量读取 API 密钥
                                                        // 需提前设置：export CONTEXT7_API_KEY=your_key
      }
    }
  }
}

在提示词中加入 use context7 即可调用文档搜索功能：

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

也可以在项目的 AGENTS.md 中添加全局规则，让 LLM 在需要查阅文档时自动使用 Context7，无需每次手动指定：

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

Grep by Vercel

添加 Grep by Vercel MCP 服务器，可以直接在对话中搜索 GitHub 上的真实代码片段，帮助 LLM 找到正确的 API 用法和实现参考：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {           // 服务器命名为 gh_grep，提示词中通过此名称引用
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

在提示词中加入 use the gh_grep tool 即可搜索 GitHub 上的代码示例：

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

同样可以在 AGENTS.md 中设置全局规则，让 LLM 在不确定用法时自动搜索代码示例：

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