OpenCode 怎么添加 MCP？本地、远端、OAuth 配置全教程
OpenCode 支持通过 MCP（Model Context Protocol）接入外部服务——本地跑的命令或远端 URL 都行。给 OpenCode 添加 MCP 本质上就是往配置文件里加一段 JSON，跑起来以后模型就多了一批可调用的工具。
懒人捷径：想接的服务不在本文例子里？直接让 AI 帮你写配置
本文后面会手把手教 Tavily（本地）和 Context7（远端）这两个具体例子，但世界上的 MCP 服务有几百上千个，不可能每一个都有教程可抄。好消息是：配置这件事本身，正好可以交给 AI 帮你做，你不需要自己看懂英文文档、也不需要自己拼 JSON。如果你懒得一步步跟着后面的手动教程走，看完这一节就够用了；如果你想彻底搞懂每个字段是什么意思，也可以先跳过这节，直接看后面的手把手部分。
方法一：把文档甩给任何一个 AI 聊天工具，让它帮你写
不管是网页版的 ChatGPT、Claude，还是别的 AI 对话工具，都能做这件事。步骤是：
- 去你想接入的那个服务的官网，找到它写着 “MCP”、“MCP Server” 字样的那个页面（一般在文档里搜 “MCP” 两个字母就能找到），把这个页面的网址复制下来。
- 打开任意一个 AI 聊天网页，把下面这段话复制过去，只需要把里面的”服务文档链接”换成你刚才复制的那个网址，其他不用改：
我在用一个叫 OpenCode 的 AI 编程工具，它靠 MCP 协议接入外部服务。
我想接入这个服务：服务文档链接
请你阅读这个页面，然后：
1. 告诉我这个服务的 MCP 应该配成 local 类型还是 remote 类型
2. 给我一段完整、可以直接粘贴进 opencode.json 文件里 "mcp" 字段下的 JSON 配置
3. 告诉我这个配置需要哪些环境变量（比如 API Key），变量名具体叫什么
4. 用最简单的话告诉我，这些环境变量的值应该去哪里注册/获取
不需要过多解释，先给我第 2 步的 JSON，再简单列 3、4 步的答案。- AI 会给你一段现成的 JSON 和一份”要去哪里注册 Key”的说明。照着本文后面 Tavily 例子里”记环境变量 → 打开配置文件粘贴 →
opencode mcp list验证 →use 名字测试”这四步走一遍就行，方法完全一样，换的只是里面的服务名字和字段内容。
这里有个坑要注意： AI 偶尔会编造一个根本不存在的字段名或者错误的网址（这叫”AI 幻觉”）。所以拿到 JSON 之后，可以追问它一句”你刚才这些字段名是从文档原文哪里看到的，原文截给我看看”，如果它答不上来或者对不上，就换个说法让它重新确认一遍原始文档内容，别直接盲信。
方法二：更省事的做法——直接让 OpenCode 自己动手改
如果你已经把 OpenCode 装好、也接通了至少一个 MCP（比如本文后面的 Tavily 例子），那你手头其实已经有一个能读文件、能改文件的 AI 助手了——OpenCode 本身。这种情况下可以更懒一点，直接在 OpenCode 对话框里说：
我想给自己接入 XXX 这个服务的 MCP，它的文档在 服务文档链接。
请你帮我读一下这个文档，然后直接把配置加进
~/.config/opencode/opencode.json 这个文件里的 mcp 字段下面，
不要覆盖里面已经有的其他配置。
需要用到的 API Key，我等会儿会自己存进环境变量里，
你在配置里用 {env:变量名} 的写法就行，不要直接把 Key 写死在文件里。
改完之后告诉我这个环境变量该叫什么名字，我好去对应的网站上注册申请。OpenCode 会自己去读文档、自己打开配置文件、自己把 JSON 写进去（第一次这么做的时候，它可能会弹出一个”允许编辑这个文件吗”的确认框，点允许/同意就行）。你只需要按它告诉你的变量名，回到终端执行本文后面教过的 echo 'export 变量名="你的key"' >> ~/.zshrc 这一行，再开个新终端窗口，跑一次 opencode mcp list 确认状态是 configured / ready 就大功告成了。
配置文件放哪
- 全局用：
~/.config/opencode/opencode.json - 只给当前仓库：项目根目录的
opencode.json，可以提交 Git
多处都有配置时，同名键后面覆盖前面，不冲突的键合并保留。文件头带上 Schema 方便编辑器补全：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {}
}本地 MCP
type: "local"，command 是启动命令的数组：
{
"mcp": {
"my-mcp": {
"type": "local",
"command": ["npx", "-y", "my-mcp-package"],
"environment": {
"SOME_VAR": "value"
}
}
}
}environment 注入子进程的环境变量，适合放路径之类的非密钥配置。密钥用 {env:变量名} 占位从宿主 shell 里取，不要硬写进文件。
第一次配可以先接 @modelcontextprotocol/server-everything 验证整条链路通不通：
{
"mcp": {
"everything": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
}
}
}对话里说 use everything，确认工具列表出来了再换真正要用的 MCP。
实战示例：接入 Tavily 搜索 MCP（手把手，零基础也能跟着做）
前面几段是写给已经懂配置文件的人看的。这一节换一种方式：假设你从没写过代码、也没打开过”终端”，我们一步一步、不跳过任何一个动作地把 Tavily（一个能让 AI 联网搜索的服务）接进 OpenCode。
先说清楚要做的事情一共分五步：① 注册账号拿一个”钥匙”（Key） → ② 把这把钥匙安全地记在电脑里 → ③ 打开一个文件、粘贴一段内容 → ④ 让 OpenCode 重新读一次配置 → ⑤ 测试能不能用。 每一步具体怎么做，往下看。
开始之前：配置文件里那几个词是什么意思
第三步会让你往一个文件里粘贴一段内容，长这样（下面每一行后面 // 开头的文字是注释，只是讲给你听的，实际文件里不需要也不能写这些注释，真正要粘贴的干净版本在第三步里）：
{
"mcp": { // 固定写法：接下来列的都是外部服务
"tavily": { // 你自己起的名字，之后 use 这个名字
"type": "local", // 运行方式：local = 在自己电脑上跑
"command": ["npx", "-y", "tavily-mcp@latest"], // 具体怎么跑：见下面逐项解释
"environment": { // 塞给这个小程序的"纸条"（比如密钥）
"TAVILY_API_KEY": "{env:TAVILY_API_KEY}" // 纸条内容去环境变量里取，不明文写
}
}
}
}这一整段东西的格式叫 JSON，你可以把它理解成一张”表格”，只不过不是用 Excel 那种格子画出来的，而是用 { } 花括号和 " " 引号画出来的。表格里的每一行，都是”某个字段 = 某个值”，冒号 : 左边是字段名字，右边是这个字段被填成了什么。跟填一张报名表很像："姓名": "张三" 就是”姓名”这个字段，填的值是”张三”。
下面把你会看到的每一个字段，一个一个讲清楚：
mcp：固定写法，意思是”接下来要列的都是外部服务”，不用改，也不用管它是什么意思，照抄就行。tavily：这是你自己给这个服务起的名字，起别的名字也完全可以，比如叫search、我的搜索工具都行。之后你在对话里输入use tavily时，用的就是这里起的这个名字，所以名字和后面use的时候要保持一致。type：这个服务”怎么跑起来”的类型，只有两种固定选项可以填："local"：意思是”在你自己电脑上跑一个小程序”，Tavily 用的就是这种。"remote"：意思是”直接连到网上别人已经开好的一个服务地址”，不需要在你电脑上跑程序（后面”远端 MCP”那节会讲）。- 这两个词必须原样照抄（包括那对引号），不能自己发明第三种写法。
command：这里第一次出现了方括号[ ]，这个东西叫数组（array），你可以直接理解成”一个有先后顺序的清单”，就像你写在纸上的购物清单：第一样买什么、第二样买什么，用逗号隔开列下去。这个清单具体是”电脑要依次执行的一条指令，被拆成了一个个词”："npx"：清单里第一项，表示”用 npx 这个工具去运行一个别人写好的小程序”（npx 是随 Node.js 一起装好的一个小工具，专门用来”临时借用”网上现成的程序，不用自己安装）。"-y"：清单里第二项，意思是”如果过程中它问你要不要确认，直接自动回答’要’“，省得手动按确认。"tavily-mcp@latest"：清单里第三项，也是最关键的一项——这是那个具体小程序的名字，@latest表示”永远用最新版本”。接别的服务时，这里换成对应服务的程序名字就行，其他两项通常不用变。- 所以整个
["npx", "-y", "tavily-mcp@latest"]连起来读，就是一句话：“借用 npx，自动确认，去运行 tavily-mcp 这个最新版的小程序”。
environment：又是一张小表格（花括号），专门用来给上面那个小程序”塞纸条”，告诉它一些运行时需要知道的信息——最常见的就是密码/Key 这类东西。这里的字段名（比如TAVILY_API_KEY）通常是服务提供方指定好的固定名字，不能随便改，改了程序会不认。"{env:TAVILY_API_KEY}"：这不是让你手打替换的占位符，而是一种固定语法，意思是”别把真实的 Key 写在这张表格里，去电脑之前记好的那个地方（也就是本文第二步设置的环境变量）取值”。这样即使这个配置文件不小心被别人看到，也看不到你真实的 Key。
一句话总结：这段配置就是在说”起个名字叫 tavily，用本地方式运行，具体运行 npx 借来的 tavily-mcp 这个程序，运行时给它一张写着 API Key 的小纸条，纸条上的内容去环境变量里拿”。 弄懂这句话，接下来照着抄就不再是”盲抄”了。
第零步：确认电脑上有没有装 npx（这是本地 MCP 能跑起来的前提）
上一节讲过，command 里的 npx 是”借用别人写好的小程序”的工具。但 npx 不是凭空存在的，它是跟着 Node.js（一个让电脑能运行 JavaScript 程序的软件）一起装进电脑的。如果你从来没装过 Node.js，npx 这个词电脑根本不认识，后面 Tavily 也就跑不起来——这一步就是先确认它在不在，不在的话先装上，全程只需要做一次，以后配置别的 MCP 也不用再装。
怎么确认： 先打开终端——按住 command 键（⌘）不放，同时按一下空格键，屏幕中间会跳出一个搜索框，打出”终端”或英文 Terminal，看到黑白方框图标后按回车，就会打开一个新窗口（后面第二步会再详细讲一次终端，这里先照做能打开就行）。打开后复制粘贴下面这行，回车：
npx -v- 如果回车后出现一串数字（比如
10.9.2这样），说明已经装好了，直接跳到下面的”第一步”。 - 如果提示类似
command not found: npx（意思是”没找到这个命令”），说明还没装，往下看怎么装。
怎么装 Node.js（连带装好 npx）：
- 打开浏览器，访问 nodejs.org。
- 网页上通常会有一个显眼的绿色下载按钮，写着 LTS（这是”长期稳定版”的意思，选它就对了，不要选写着 Current 的那个）。点它下载一个安装包。
- 下载完成后，在”下载”文件夹里找到那个安装包（文件名类似
node-v22.x.x.pkg），双击打开它。 - 接下来就跟安装普通 Mac 软件一模一样：一路点”继续”（Continue）→“同意”（Agree）→“安装”（Install），中间可能会让你输一次电脑的开机密码，输完回车就行，最后点”关闭”（Close）。
- 重新打开一个新的终端窗口（跟前面强调过的一样，装完东西要用新窗口才会认得到），再执行一次
npx -v确认，这次应该能看到版本号了。
确认 npx -v 能正常显示出一串数字之后，再继续往下做第一步。
第一步：注册 Tavily，拿到你的 API Key
“API Key” 可以理解成一串专属于你的密码，你把它交给 OpenCode，OpenCode 就能代表你去使用 Tavily 的搜索服务，Tavily 那边也知道该给谁记账（免费额度内不花钱）。
- 打开浏览器，访问 tavily.com。
- 用邮箱注册一个账号（跟注册任何一个普通网站一样，填邮箱、设密码、验证邮箱）。
- 登录后你会进入一个叫 “Dashboard”（仪表盘，就是账号的管理主页）的页面，上面会有一长串英文字母和数字，通常长这样：
tvly-xxxxxxxxxxxxxxxx。 - 点它旁边的复制按钮，把这一整串复制下来，先粘贴到备忘录 App 里存着——这就是你的 Key，等下要用。不要把它发给别人，也不要发到群里或者截图发朋友圈，它相当于一把能替你花钱/调用服务的钥匙。
第二步：打开终端，把 Key 安全地记下来
“终端”（Terminal）是 Mac 自带的一个 App，长得像一个黑色或白色的窗口，里面只能打字、没有按钮。它是用来跟电脑”直接对话”的工具，接下来我们只会用到几行很短的指令，照着打（或复制粘贴）就行，不需要看懂。
怎么打开终端：
- 按一下 Mac 键盘上的
command键（键盘上写着 ⌘ 的那个）不放，同时按一下空格键，屏幕中间会跳出一个搜索框（这叫 Spotlight）。 - 手动打出四个字：
终端，或者英文Terminal。 - 看到搜索结果里出现一个图标（黑白方框），按回车键，就会打开一个新窗口——这就是终端了。
在终端里记下你的 Key：
终端打开后，会有一行文字加一个闪烁的光标在等你输入。把下面这一整行复制下来（记得把 你复制的那串key 换成你在第一步存下来的那串真实的 Key）：
echo 'export TAVILY_API_KEY="你复制的那串key"' >> ~/.zshrc粘贴进终端窗口（在终端里粘贴通常是 command + V），然后按一下键盘上的回车键（Enter）。如果没有报红色的字、也没有弹出奇怪的提示，就说明成功了——终端本来就是这样，没消息就是好消息。
接着把这个终端窗口整个关掉，重新按上面的方法打开一个新的终端窗口（这一步是为了让刚才记下的 Key 生效，只对着同一个旧窗口是不会生效的）。
第三步：找到配置文件，粘贴一段内容进去
OpenCode 靠读一个叫 opencode.json 的文件来知道该连哪些外部服务。这个文件默认放在一个电脑里”藏起来”的文件夹里，我们直接用终端把它打开，不用自己去翻文件夹。
在新打开的终端窗口里，把下面这一整行复制、粘贴进去，回车：
open -e ~/.config/opencode/opencode.json这行命令的意思是”用 Mac 自带的文本编辑器（TextEdit）打开这个配置文件”。
- 如果这个文件之前已经存在（比如你按本文前面的内容配置过），会弹出一个记事本一样的窗口，里面已经有一些内容。
- 如果提示”文件不存在”，说明你是第一次配置，那就先在终端里粘贴执行这两行（分两次粘贴、每行回车一次），把文件夹和空文件建出来，再重新执行上面那行
open -e命令：
mkdir -p ~/.config/opencodeecho '{}' > ~/.config/opencode/opencode.json打开文件后，把里面原来的全部内容删掉（全选可以用 command + A，删除用 Delete 键），然后把下面这一整段完整复制、粘贴进去：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"tavily": {
"type": "local",
"command": ["npx", "-y", "tavily-mcp@latest"],
"environment": {
"TAVILY_API_KEY": "{env:TAVILY_API_KEY}"
}
}
}
}关于这一段，你只需要知道两件事：
"{env:TAVILY_API_KEY}"这几个字不用替换、原样保留——它的意思是”去第二步记下的那个地方，把 Key 读过来”，配置文件里因此不会明文出现你的真实 Key，更安全。- 粘贴完之后，用
command + S保存文件，然后可以直接关掉这个记事本窗口。
第四步：验证 OpenCode 有没有连上
回到终端窗口（还是刚才那个），复制粘贴下面这行，回车：
opencode mcp list回车后屏幕上会列出你配置过的服务，找到一行写着 tavily 的，它后面应该跟着 configured 或 ready 这样的字样——出现这两个词任意一个，就说明连接成功了。
如果这里没有反应，或者提示找不到 opencode 这个命令，说明 OpenCode 本身还没装好，这属于另一个问题，可以先确认 OpenCode 能不能正常打开、正常对话。
第五步：真正试一次
打开 OpenCode，进入正常对话界面，直接打这样一句话（中文也行）：
use tavily
帮我搜一下今天有哪些关于 AI Agent 的新闻如果一切顺利，AI 回复之前会先显示一小段类似 → mcp__tavily__search(...) 这样的过程提示，然后给你一个基于搜索结果整理出来的答案——这就说明 Tavily 已经真正接通了，不只是文件里写了一段没用的文字。
如果卡住了怎么办： 九成情况是 Key 记错了（第二步复制粘贴的时候多了空格或少了引号），回到第二步重新执行一遍那条 echo ... >> ~/.zshrc 的命令，注意 Key 前后一定要带着英文引号 "。
远端 MCP
type: "remote"，填 url，要鉴权就在 headers 里加 Bearer，密钥同样用 {env:...}：
{
"mcp": {
"my-remote-mcp": {
"type": "remote",
"url": "https://my-mcp-server.com",
"headers": {
"Authorization": "Bearer {env:MY_API_KEY}"
}
}
}
}实战示例：接入 Context7 文档查询 MCP（远端，零基础版）
本地 MCP（比如上面的 Tavily）要在你自己电脑上跑一个小程序；远端 MCP 不用装任何程序，就是把 OpenCode 指向别人已经开好、挂在网上的一个服务地址，你只负责”告诉它地址在哪、我是谁”。这里拿 Context7（一个能让 AI 查到最新、准确的第三方库文档的服务，比如你问”某个库最新版本的用法”，它能查到官方文档给模型看）举例。
先看懂字段：远端 MCP 比本地 MCP 少两样、多一样
{
"mcp": {
"context7": { // 你自己起的名字，之后 use 这个名字
"type": "remote", // 运行方式：remote = 连一个网上的地址
"url": "https://mcp.context7.com/mcp", // 这个服务挂在网上的具体地址
"headers": { // 连接时随手附上的"介绍信"
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" // 介绍信里写的 Key，去环境变量取
}
}
}
}跟本地 MCP 对比着看：
- 不再需要
command这个”清单”了，因为不用在自己电脑上运行任何程序，自然也没有”运行方式”这一说。 - 多了一个
url字段：就是这个远端服务的网址，照抄文档给的那一串就行，不用自己拼。 headers：连接远端服务时顺带带上的一些”身份信息”，格式还是”字段名: 值”这种小表格，具体要填哪个字段名（这里是CONTEXT7_API_KEY）由 Context7 这个服务自己规定，换成别的远端服务就得看它自己的文档写的字段名。"{env:CONTEXT7_API_KEY}"和 Tavily 例子里的用法一模一样：真实 Key 藏在环境变量里，配置文件里不明文出现。
三步接好 Context7
第一步，拿 API Key（这一步其实可以跳过）。 Context7 不强制要 Key 也能用，只是没有 Key 时查询速度和次数会受限制。如果想要更稳定，去 context7.com/dashboard 用邮箱注册一下，登录后就能在页面上复制到一个 Key，跟第一节注册 Tavily 的过程几乎一样。
第二步，把 Key 记进环境变量（跳过第一步的话，这一步也跳过）。 打开终端（打开方法见前面 Tavily 例子的”第二步”），复制粘贴：
echo 'export CONTEXT7_API_KEY="你复制的那串key"' >> ~/.zshrc回车后关掉终端窗口，重新打开一个新的。
第三步，写配置。 用同样的方式打开配置文件：
open -e ~/.config/opencode/opencode.json在原来的 "mcp" 那张小表格里，跟 "tavily" 平级，加上 "context7" 这一段（注意 tavily 那一段后面要补一个逗号 ,，因为现在同一张表格里有两项了）：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"tavily": {
"type": "local",
"command": ["npx", "-y", "tavily-mcp@latest"],
"environment": {
"TAVILY_API_KEY": "{env:TAVILY_API_KEY}"
}
},
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"headers": {
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
}
}
}
}如果你跳过了第一、二步（不打算用 Key），把 "headers" 那三行整段删掉即可，只留 "type" 和 "url" 两行。
保存（command + S）后回到终端，还是那句验证口诀：
opencode mcp list看到 context7 也变成 configured / ready，再进 OpenCode 对话里试一句：
use context7
帮我查一下 React 19 里 useActionState 这个 Hook 官方文档怎么用的回复前面出现 → mcp__context7__... 这样的调用记录，就说明这个远端 MCP 也接通了。
走 OAuth 的服务（比如 Sentry）更简单，oauth: {} 触发自动流程，之后手动跑一次 opencode mcp auth sentry 过浏览器登录：
{
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}OAuth 令牌落在 ~/.local/share/opencode/mcp-auth.json，不要提交进公开仓库。
常用 CLI
opencode mcp list # 看所有 MCP 和认证状态
opencode mcp auth <名字> # 手动触发 OAuth 登录
opencode mcp logout <名字> # 清凭证重登
opencode mcp debug <名字> # 排查 HTTP / OAuth 问题配完之后长什么样
配置文件本身不复杂，但容易卡在「我配好了，怎么知道真的生效了」。下面是接一个真实 MCP（以 Sentry 为例）的完整闭环。
第一步，确认连上。 配好 opencode.json 后跑：
opencode mcp list输出里每个 MCP 会有一个认证状态。显示 configured / ready 才算通，error 要先 opencode mcp debug <名字> 排查（多半是 URL、密钥或 OAuth 没走完）。
第二步，进对话显式调用。 新挂的 MCP 有时候不会被模型自动选中（下一个坑会讲），所以第一次最好显式点名：
use sentry
帮我看一下 qunqin-blog 这个项目最近 24 小时有没有新报错，按频率排个序。正常情况下模型会回一段工具调用的过程，类似：
→ mcp__sentry__list_issues(project="qunqin-blog", statsPeriod="24h")
← [{ id: "...", count: 3, title: "TypeError: ..." }, ...]能看见这一行 → 调用和 ← 返回，说明整条链路通了——配置、鉴权、工具注册都没问题。
第三步，确认密钥没漏。 这个常被忽略：opencode.json 如果不小心提交进 Git，里面用 {env:...} 占位的部分是安全的，但 OAuth token 落在 ~/.local/share/opencode/mcp-auth.json——确认它在 .gitignore 覆盖范围内，或者干脆不放进仓库目录。
走完这三步，一个 MCP 才算真正「能用」，而不是「配上了」。
两个小坑
挂的 MCP 多了以后，模型有时候会假装没看见工具。提示里显式写 use xxx（xxx 是配置里的键名）能改善这个问题。
每个 MCP 都消耗上下文。GitHub 类的返回量特别大，窗口容易塞满——能少挂就少挂，或者用 tools + glob 按 agent 粒度限制。