>_OpenCode
~/content/mcp-服务器

MCP 服务器

添加本地和远程 MCP 工具。

last_updated: "2026-01-20"

你可以使用 Model Context Protocol (MCP) 将外部工具添加到 OpenCode。OpenCode 支持本地和远程服务器。

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

注意事项

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

Note

💡 提示

MCP 服务器会添加到你的上下文中，因此你需要小心启用哪些服务器。

某些 MCP 服务器，例如 GitHub MCP 服务器，往往会添加大量 tokens，并且很容易超过上下文限制。

##启用

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

bash
{
  "$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:

bash
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

你的本地配置值会覆盖远程默认值。有关更多详细信息，请参阅 配置优先级。

##本地

使用 type 到 "local" 在 MCP 对象中添加本地 MCP 服务器。

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

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

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

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

bash
{
  "$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 选项传入一个 headers 列表。

选项

| 选项 | 类型 | 必需 | 描述 | | --------- | ------- | -------- | ----------------------------------------------------------------------------------- | | type | String | Y | MCP 服务器连接的类型，必须是 "remote"。 | | url | String | Y | 远程 MCP 服务器的 URL。 | | enabled | Boolean | | 启动时启用或禁用 MCP 服务器。 | | headers | Object | | 随请求一起发送的 Headers。 | | oauth | Object | | OAuth 身份验证配置。请参阅下面的 OAuth 部分。 | | timeout | Number | | 从 MCP 服务器获取工具的超时时间（以毫秒为单位）。默认为 5000（5 秒）。 |

##OAuth

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

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

###自动

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

bash
{
  "$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 服务器提供商的客户端凭据，你可以配置它们：

bash
{
  "$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 会将 tokens 安全地存储在 ~/.local/share/opencode/mcp-auth.json 中。

禁用 OAuth

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

bash
{
  "$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 | Object | false | OAuth 配置对象，或 false 以禁用 OAuth 自动检测。 | | clientId | String | OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。 | | clientSecret | String | OAuth 客户端密钥，如果授权服务器需要。 | | scope | String | 授权期间要请求的 OAuth 范围。 |

调试

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

bash
# View auth status for all OAuth-capable servers
opencode mcp auth list

# Debug connection and OAuth flow for a specific server
opencode mcp debug my-oauth-server

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

##管理

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

###全局

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

bash
{
  "$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。

bash
{
  "$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。

###每个 Agent

如果你有大量的 MCP 服务器，你可能只想为每个 Agent 启用它们，并全局禁用它们。为此：

  1. 将其作为工具全局禁用。
  2. 在你的 Agent 配置 中，将 MCP 服务器作为工具启用。
bash
{
  "$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 模式使用简单的正则表达式 globbing 模式：

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

📝 注意

MCP 服务器工具以服务器名称作为前缀注册，因此要禁用服务器的所有工具，只需使用：

bash
"mymcpservername_*": false

##示例

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

###Sentry

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

bash
{
  "$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 工具来查询问题、项目和错误数据。

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

###Context7

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

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

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

bash
{
  "$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 服务器。

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

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

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

###Grep by Vercel

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

bash
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

由于我们将 MCP 服务器命名为 gh_grep，因此你可以将 use the gh_grep tool 添加到你的提示中以使 Agent 使用它。

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

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

bash
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
Comments (Coming Soon)

Configure Giscus in environment variables to enable comments.