>_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 服务器的所有选项。

选项类型必需描述
typeStringYMCP 服务器连接的类型，必须是 "local"。
commandArrayY运行 MCP 服务器的命令和参数。
environmentObject运行服务器时要设置的环境变量。
enabledBoolean启动时启用或禁用 MCP 服务器。
timeoutNumber从 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 列表。

选项

选项类型必需描述
typeStringYMCP 服务器连接的类型，必须是 "remote"。
urlStringY远程 MCP 服务器的 URL。
enabledBoolean启动时启用或禁用 MCP 服务器。
headersObject随请求一起发送的 Headers。
oauthObjectOAuth 身份验证配置。请参阅下面的 OAuth 部分。
timeoutNumber从 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 选项

选项类型描述
oauthObject | falseOAuth 配置对象，或 false 以禁用 OAuth 自动检测。
clientIdStringOAuth 客户端 ID。如果未提供，将尝试动态客户端注册。
clientSecretStringOAuth 客户端密钥，如果授权服务器需要。
scopeString授权期间要请求的 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.