OpenCode 中文教程

Appearance

5.7a MCP 基础 ​

💡 一句话总结：通过 MCP（Model Context Protocol）连接外部服务，让 AI 能调用数据库、搜索引擎、监控平台等任意工具。

📝 课程笔记 ​

本课核心知识点整理：

MCP基础学霸笔记

学完你能做什么 ​

  • 理解 MCP 协议的作用和架构
  • 配置本地 MCP 服务器
  • 配置远程 MCP 服务器
  • 查看 MCP 连接状态

你现在的困境 ​

  • AI 只能操作本地文件，访问不了外部服务
  • 想让 AI 查 Sentry 日志、搜索文档、操作数据库
  • 听说过 MCP，但不知道怎么配置和使用

什么是 MCP ​

MCP（Model Context Protocol）是一种标准协议，让 AI 能调用外部工具和服务。

核心概念：

  • MCP 服务器：提供工具的外部进程或远程服务
  • MCP 工具：服务器暴露的具体功能（如搜索、查询、操作）
  • MCP 客户端：OpenCode 内置的连接器

工作原理：

用户提问 → OpenCode → AI 决定调用 MCP 工具 → MCP 服务器执行 → 返回结果

注意事项 ​

  • MCP 服务器会增加上下文消耗，工具越多 token 消耗越快
  • 某些 MCP（如 GitHub）会添加大量 token，容易超出上下文限制
  • 建议只启用必要的 MCP 服务器

本地 MCP 服务器 ​

本地 MCP 服务器运行在你的机器上，通过 stdio 通信。

配置方式 ​

在 opencode.jsonc 的 mcp 下配置：

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

配置选项 ​

选项类型必填描述
typeString✓必须是 "local"
commandArray✓命令数组，如 ["npx", "-y", "xxx"] 或 ["bun", "x", "xxx"]
environmentObject环境变量键值对
enabledBoolean是否启用，默认 true
timeoutNumber连接超时（毫秒），默认 30000

⚠️ 注意：官方文档描述 timeout 默认值为 5000ms，但源码实际默认值为 30000ms（30秒）。来源：mcp/index.ts:29

使用方式 ​

配置完成后，在对话中添加提示词引导 AI 使用：

use the my-local-mcp tool to do something

远程 MCP 服务器 ​

远程 MCP 服务器通过 HTTP/SSE 协议连接。

配置方式 ​

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

配置选项 ​

选项类型必填描述
typeString✓必须是 "remote"
urlString✓远程 MCP 服务器 URL
enabledBoolean是否启用，默认 true
headersObject自定义请求头
oauthObject/falseOAuth 配置或禁用 OAuth
timeoutNumber连接超时（毫秒），默认 30000

连接状态 ​

MCP 连接有 5 种状态：

状态说明
connected已连接，工具可用
disabled配置中 enabled: false，未连接
failed连接失败，查看错误信息
needs_auth需要 OAuth 认证
needs_client_registration需要预注册客户端 ID

查看当前状态：

bash
opencode mcp list

快速开始示例 ​

示例 1：本地测试服务器 ​

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

测试使用：

use the everything tool to add 3 and 4

示例 2：Context7 文档搜索 ​

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

测试使用：

use context7 查询 React hooks 最佳实践

示例 3：Grep 代码搜索 ​

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

测试使用：

use the gh_grep tool 搜索如何在 Node.js 中实现 JWT 验证

踩坑提醒 ​

现象原因解决
MCP 连接超时timeout 设置过短或网络慢增大 timeout 值，默认 30000ms
本地 MCP 启动失败命令不存在或路径错误确认 command 数组正确，检查 PATH
远程 MCP 连接失败URL 错误或服务器不可用验证 URL 是否正确，检查网络

本课小结 ​

你学会了：

  1. MCP 协议：让 AI 连接外部服务的标准协议
  2. 本地 MCP：type: "local" + command 数组
  3. 远程 MCP：type: "remote" + url
  4. 连接状态：5 种状态及查看方法

下一步 ​

遇到问题？

MCP 配置卡住了？加入社群，和 500+ 同路人一起交流，实时答疑。