MCP 服务器与插件

MCP 服务器

你可以用 Model Context Protocol（MCP）给 OpenCode 添加外部工具，支持本地和远程服务器。添加后，MCP 工具与内置工具一起自动对 LLM 可用。注意：使用 MCP 服务器会增加上下文，如果有很多工具会迅速累积，所以要谨慎选择 MCP 服务器；有些服务器（如 GitHub MCP 服务器）往往添加大量 token，很容易超出上下文限制。

在 OpenCode 配置的 mcp 下定义 MCP 服务器，每个起一个唯一的名字，提示 LLM 时可以按名字引用。把 enabled 设为 false 可以临时禁用而不从配置里移除。覆盖远程默认值：组织可以通过 .well-known/opencode 端点提供默认的 MCP 服务器（可能默认禁用，让用户选择性启用），在本地配置里为它加上 enabled: true 即可启用，本地配置值覆盖远程默认值。

本地服务器：type 设为 "local"：

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

之后在提示里写「use the mcp_everything tool to add the number 3 and 4」就能使用它。选项：type（必填，"local"）；command（必填，运行 MCP 服务器的命令和参数数组）；cwd（MCP 服务器进程的工作目录，相对路径从工作区解析）；environment（运行服务器时设置的环境变量）；enabled（启动时启用或禁用）；timeout（从 MCP 服务器获取工具的超时毫秒数，默认 5000）。

远程服务器：type 设为 "remote"：

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

选项：type（必填，"remote"）、url（必填，远程 MCP 服务器的 URL）、enabled、headers（要传的请求头）。需要 OAuth 的服务器用 opencode mcp auth 认证。

插件

插件让你通过挂接各种事件和定制行为来扩展 OpenCode：可以添加新功能、集成外部服务或修改 OpenCode 的默认行为。使用插件有两种方式：本地文件（把 JavaScript 或 TypeScript 文件放进插件目录：.opencode/plugins/ 项目级、~/.config/opencode/plugins/ 全局，启动时自动加载）；从 npm（在配置文件里指定 npm 包，支持普通和作用域包）：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

npm 插件在启动时用 Bun 自动安装，包及其依赖缓存在 ~/.cache/opencode/node_modules/；本地插件直接从插件目录加载，要使用外部包，需要在配置目录里创建 package.json。加载顺序：插件从所有来源加载，所有 hooks 按顺序运行：全局配置（~/.config/opencode/opencode.json）、项目配置（opencode.json）、全局插件目录、项目插件目录。同名同版本的重复 npm 包只加载一次，但本地插件和名字相似的 npm 插件会分别加载。创建插件：插件是导出一个或多个插件函数的 JavaScript/TypeScript 模块，每个函数接收一个上下文对象并返回一个 hooks 对象；可用的事件和 hooks 见官方 Plugins 页。