WenHaoFree
所有文章 标签 分类 图册 关于 主页
WenHaoFree

目录

OpenCode MCP 配置指南:扩展 AI 上下文能力的完整教程

 收录于 开发工具
   约 1922 字   预计阅读 4 分钟 

本文将教你:

  • 什么是 MCP 及其工作原理
  • 如何配置本地 MCP 服务 (shadcn 等)
  • 如何配置远程 MCP 服务 (Context7 等)
  • 混合配置多个 MCP 服务的方法
  • 验证配置和故障排查技巧

什么是 MCP (Model Context Protocol)?

Model Context Protocol (MCP) 是一种标准化协议,用于为 AI 模型提供外部上下文和工具访问能力。通过 MCP,OpenCode 可以连接到本地脚本、远程知识库或专用服务,从而理解特定领域知识或调用外部工具。协议支持本地命令执行和远程 HTTP 端点两种接入方式,并可通过 OAuth 或 API Key 进行认证。

本文将介绍如何在 OpenCode 中配置 MCP (Model Context Protocol) 服务。通过配置 MCP，你可以让 OpenCode 连接到本地或远程的上下文服务，从而增强其对特定领域知识或工具的理解能力。

配置方式

OpenCode 支持两种 MCP 配置方式：

  1. 本地方式 (Local)：运行本地命令或脚本作为 MCP 服务。
  2. 远程方式 (Remote)：连接到远程 HTTP/HTTPS MCP 服务端点。

1. 定位配置文件

OpenCode 的主要配置文件为 opencode.json。

macOS / Linux 路径：

~/.config/opencode/opencode.json

(即用户主目录下的 .config/opencode/ 文件夹内)

2. 编辑配置

打开 opencode.json 文件，找到 JSON 对象的最外层（通常与 plugins 平级），添加或修改 "mcp" 字段。

场景 A：仅配置本地 MCP (以 shadcn 为例)

如果你只需要运行一个本地的 MCP 服务，例如 shadcn 的 MCP，可以如下配置：

{
  "mcp": {
    "shadcn": {
      "type": "local",
      "command": ["npx", "-y", "shadcn@latest", "mcp"],
      "enabled": true
    }
  }
}

场景 B：混合配置 (本地 + 远程)

如果你需要同时连接本地工具和远程知识库（例如 Context7），可以按以下格式组合配置：

{
  "mcp": {
    "shadcn": {
      "type": "local",
      "command": ["npx", "-y", "shadcn@latest", "mcp"],
      "enabled": true
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

注意：

  • JSON 格式必须严格正确，确保逗号放置无误。
  • 对于远程服务，请务必替换 API-KEY 为你实际的授权密钥。

3. 验证配置

配置保存后，需要重启 OpenCode 或重新加载配置以生效。

  1. 打开一个新的 OpenCode 终端窗口。
  2. 输入验证命令：
    /mcps
  3. 检查输出：
    • 如果配置成功，OpenCode 将回显当前已加载的 MCP 服务列表及其状态。
    • 如果出现错误提示，请检查 opencode.json 的 JSON 语法是否正确，以及命令或 URL 是否可访问。

https://image.wenhaofree.com/2026/01/8abef3bff423cdd49eac13a7269afd11.png

通过以上步骤，你已成功为 OpenCode 接入了 MCP 服务，现在可以尝试询问与接入服务相关的问题，测试其增强的上下文能力。

故障排查

问题 1: /mcps 命令无输出或显示为空

症状: 运行 /mcps 后没有任何返回或显示空列表。

可能原因:

  • config.yaml 文件路径错误
  • JSON 格式错误 (多余逗号、缺少引号等)
  • MCP 配置未保存或未重启 OpenCode

解决方案:

# 1. 验证配置文件格式是否正确
cat ~/.config/opencode/opencode.json | python3 -m json.tool

# 2. 检查文件权限
ls -la ~/.config/opencode/

# 3. 重新启动 OpenCode (新开终端窗口)
opencode

# 4. 查看 OpenCode 日志
tail -f ~/.config/opencode/logs/latest.log

问题 2: 本地 MCP 服务启动失败

症状: 配置了 shadcn 等本地 MCP,但提示 command not found 或无法启动。

可能原因:

  • npx 命令不可用
  • Node.js 版本过低
  • command 数组格式错误

解决方案:

# 1. 确认 npx 可用
which npx
node --version  # 需要 v16+

# 2. 手动测试命令是否能运行
npx -y shadcn@latest mcp

# 3. 检查 command 数组格式 (必须是字符串数组)
# ✅ 正确: ["npx", "-y", "shadcn@latest", "mcp"]
# ❌ 错误: "npx -y shadcn@latest mcp"

问题 3: 远程 MCP 认证失败

症状: 配置了远程 MCP 服务,但提示 401 Unauthorized 或 403 Forbidden。

可能原因:

  • API Key 错误或已过期
  • headers 配置格式错误

解决方案:

# 1. 验证 API Key 是否有效 (使用 curl 测试)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://mcp.context7.com/mcp

# 2. 检查 headers 配置格式
# ✅ 正确格式:
"headers": {
  "Authorization": "Bearer sk-xxx..."
}

# 3. 确认 URL 是否正确 (注意末尾斜杠)

问题 4: MCP 服务加载但不生效

症状: /mcps 显示服务已加载,但对话中无法使用相关功能。

解决方案:

# 1. 确认 "enabled": true
# 2. 检查服务是否返回错误 (查看日志)
# 3. 尝试明确询问相关问题
> 使用 shadcn MCP 帮我查找 Button 组件的用法

常见问题 (FAQ)

Q1: 本地和远程 MCP 有什么区别?

A: 主要区别在于运行方式和适用场景:

类型本地 MCP远程 MCP
运行方式启动本地命令/脚本连接 HTTP/HTTPS 服务
适用场景文件操作、代码工具、本地数据库知识库查询、API 调用、云服务
网络要求无需网络需要稳定网络连接
认证方式通常无需认证OAuth / API Key
示例服务shadcn, 本地脚本Context7, 知识库 API

Q2: 可以同时配置多个 MCP 服务吗?

A: 可以。在 mcp 对象下添加多个服务配置即可,OpenCode 会自动加载所有 enabled: true 的服务。例如:

{
  "mcp": {
    "shadcn": { "enabled": true, ... },
    "context7": { "enabled": true, ... },
    "custom-tool": { "enabled": true, ... }
  }
}

所有启用的服务会并行加载,OpenCode 会根据上下文自动选择合适的服务。

Q3: 如何查看 MCP 调用日志?

A: 有两种方法:

方法一: 启动 OpenCode 时添加详细日志参数

opencode --verbose

方法二: 查看日志文件

# 实时查看日志
tail -f ~/.config/opencode/logs/latest.log

# 搜索 MCP 相关日志
grep -i "mcp" ~/.config/opencode/logs/latest.log

Q4: MCP 服务会增加响应延迟吗?

A: 会有轻微影响:

  • 本地 MCP: 延迟通常 < 100ms,影响很小
  • 远程 MCP: 取决于网络和服务器响应速度,通常 200-500ms

OpenCode 会智能地只在必要时调用 MCP 服务,不会影响普通对话的响应速度。

Q5: 如何临时禁用某个 MCP 服务?

A: 修改配置文件,将 enabled 设为 false:

{
  "mcp": {
    "shadcn": {
      "type": "local",
      "command": ["npx", "-y", "shadcn@latest", "mcp"],
      "enabled": false  // 设为 false 禁用
    }
  }
}

保存后重启 OpenCode 即可生效。

Q6: 如何创建自己的 MCP 服务?

A: 你可以创建自定义的本地 MCP 服务:

  1. 编写脚本 (Python/Node.js/Shell)
  2. 实现 MCP 协议 (接收 stdin,输出 JSON 到 stdout)
  3. 在配置中添加:
{
  "mcp": {
    "my-custom-tool": {
      "type": "local",
      "command": ["python3", "/path/to/your/mcp_script.py"],
      "enabled": true
    }
  }
}

参考 MCP 协议规范 了解详细实现方法。

相关教程

想要进一步提升 OpenCode 的能力？推荐阅读:

更新于 2026-01-24
 OpenCode, MCP, 配置教程, AI工具, 协议集成
返回 | 主页