MCP 服务集成

MCP（Model Context Protocol）是一种标准化协议，允许 AI 模型与外部工具和服务进行交互。OpenCode 支持本地和远程 MCP 服务器，配置后工具会自动提供给 LLM 使用。

配置结构

在 opencode.json 的 mcp 对象下定义服务器：

{
  "mcp": {
    "server-name": {
      "type": "local" | "remote",
      "enabled": true,
      ...
    }
  }
}

本地服务器配置

运行在本地的 MCP 服务器：

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "environment": {
        "API_KEY": "{env:MY_API_KEY}"
      },
      "enabled": true,
      "timeout": 5000
    }
  }
}

配置字段

字段	类型	必填	说明
type	string	是	必须为 "local"
command	string[]	是	启动命令和参数
environment	object	否	环境变量
enabled	boolean	否	是否启用（默认 true）
timeout	number	否	工具获取超时（毫秒，默认 5000）

远程服务器配置

连接到远程 MCP 服务器：

{
  "mcp": {
    "remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:API_KEY}"
      },
      "enabled": true
    }
  }
}

配置字段

字段	类型	必填	说明
type	string	是	必须为 "remote"
url	string	是	服务器 URL
headers	object	否	请求头（如授权信息）
oauth	object/false	否	OAuth 配置
enabled	boolean	否	是否启用（默认 true）

常用 MCP 服务

Context7 - 上下文管理

智能上下文管理，优化 Token 使用：

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

文件系统 MCP

提供文件读写能力：

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-filesystem", "--root", "."],
      "enabled": true
    }
  }
}

Git MCP

提供 Git 操作能力：

{
  "mcp": {
    "git": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-git"],
      "enabled": true
    }
  }
}

GitHub MCP

GitHub 仓库操作（注意：可能增加大量上下文 token）：

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      },
      "enabled": true
    }
  }
}

Exa Web Search

AI 优化的网络搜索：

{
  "mcp": {
    "exa": {
      "type": "local",
      "command": ["npx", "-y", "exa-mcp-server", "tools=web_search_exa"],
      "environment": {
        "EXA_API_KEY": "{env:EXA_API_KEY}"
      },
      "enabled": true
    }
  }
}

OAuth 认证

OpenCode 支持三种 OAuth 认证方式：

自动认证（推荐）

服务器支持动态客户端注册时自动处理：

{
  "mcp": {
    "server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

预注册凭证

使用已有的 OAuth 凭证：

{
  "mcp": {
    "server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:CLIENT_ID}",
        "clientSecret": "{env:CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

禁用 OAuth

使用 API 密钥认证时禁用 OAuth：

{
  "mcp": {
    "server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:API_KEY}"
      }
    }
  }
}

认证命令

# 手动触发认证
opencode mcp auth <server-name>

# 列出所有服务器和认证状态
opencode mcp list

# 移除凭证
opencode mcp logout <server-name>

# 调试 MCP 服务器
opencode mcp debug <server-name>

工具管理

在 tools 配置中管理 MCP 工具的启用状态：

全局禁用特定 MCP 工具

{
  "tools": {
    "my-mcp*": false
  }
}

按代理启用

{
  "tools": {
    "github*": false
  },
  "agent": {
    "github-agent": {
      "description": "GitHub 操作专家",
      "tools": {
        "github*": true
      }
    }
  }
}

完整配置示例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-filesystem", "--root", "."],
      "enabled": true
    },
    "git": {
      "type": "local",
      "command": ["npx", "-y", "@anthropic/mcp-git"],
      "enabled": true
    },
    "exa": {
      "type": "local",
      "command": ["npx", "-y", "exa-mcp-server"],
      "environment": {
        "EXA_API_KEY": "{env:EXA_API_KEY}"
      },
      "enabled": true
    }
  },
  "tools": {
    "context7*": true,
    "filesystem*": true,
    "git*": true,
    "exa*": true
  }
}

上下文注意事项

⚠️ 重要：MCP 服务器会增加上下文大小。某些服务器（如 GitHub）可能添加大量 token，请谨慎选择启用的服务器。

优化建议

1. 只启用需要的服务器
2. 为特定代理启用特定工具
3. 监控 token 使用量

# 查看 token 使用统计
opencode stats

调试 MCP 服务

查看服务状态

# 列出所有 MCP 服务器
opencode mcp list

# 调试特定服务器
opencode mcp debug <server-name>

手动测试

# 直接运行 MCP 服务查看输出
npx -y @anthropic/mcp-filesystem --root .

启用调试日志

opencode --print-logs

常见问题

MCP 服务启动失败

1. 检查 Node.js 版本是否 >= 18
2. 检查 npx 是否可用
3. 检查网络连接（首次运行需要下载包）

# 验证 npx 可用
npx --version

# 预先安装包
npm install -g @anthropic/mcp-filesystem

MCP 服务超时

增加超时时间：

{
  "mcp": {
    "slow-server": {
      "type": "local",
      "command": ["npx", "-y", "slow-mcp-server"],
      "timeout": 30000
    }
  }
}

认证失败

# 重新认证
opencode mcp logout <server-name>
opencode mcp auth <server-name>

工具不可用

1. 确认服务器已启用："enabled": true
2. 确认工具未被禁用：检查 tools 配置
3. 查看服务器状态：opencode mcp list

下一步

• LSP 配置 - 配置语言服务器
• 配置详解 - 了解完整配置结构
• Agents 代理系统 - 配置自定义代理