使用说明
OpenCode MCP服务器
MCP服务器,将OpenCode作为IDE和AI客户端的工具/子代理公开
概述
OpenCode MCP Server允许任何兼容MCP的客户端(Cursor、Windsurf、Claude Desktop、Claude Code、OpenCode、Antigravity、Zed等)将编码任务委托给OpenCode作为子代理。这实现了强大的多工具工作流程,您的主要AI助手可以调用OpenCode来:
- 代码实现和重构
- 文件操作和搜索
- 代码分析和规划
- 多圈编码会话
- 代理委托(构建、规划、定制代理)
- 模型和提供商管理
- 技能发现和创造
- 子MCP服务器管理
特性
- 完整的OpenCode集成:通过MCP工具访问所有OpenCode功能
- 21工具:简化了用于编码、配置、代理、技能和MCP管理的工具集
- 混合配置持久性:配置更改会立即应用并持续到
opencode.json - 工具注释:符合MCP的注释,可更好地发现LLM
- 双重运输:stdio(本地)和HTTP(远程),具有无状态/有状态模式
- 类型安全:通过Zod v4验证完全支持TypeScript
- 可操作错误:错误消息包括具体的解决建议
- 请求超时:可配置的超时处理,并进行适当的清理
- 结构化日志记录:通过环境变量调试、信息、警告、错误级别
- 会话管理:创建和管理编码会话
- 代理委托:将任务委托给专业代理(构建、规划、探索)
- 技能系统:发现并创建可重复使用的技能定义
- MCP管理:列出并启用/禁用MCP服务器
快速开始
安装
# Clone the repository
git clone https://github.com/Traves-Theberge/opencode-mcp.git
cd opencode-mcp
# Install dependencies and build
npm install
npm run build
先决条件
- 已安装OpenCode: 安装OpenCode
- OpenCode服务器正在运行:从以下内容开始
opencode serve或TUI - 已配置API密钥:在OpenCode中设置LLM提供者密钥
- 此MCP服务器已构建:运行
npm run build在项目目录中
在IDE中配置
OpenCode MCP Server适用于所有主要的支持AI的IDE:
| IDE | 配置文件 | 安装指南 |
|---|---|---|
| Codex CLI | ~/.codex/config.toml |
完整指南 |
| Gemini CLI | ~/.gemini/settings.json |
完整指南 |
| Roo代码 | mcp_settings.json 或 .roo/mcp.json |
完整指南 |
| 反重力 | ~/.gemini/antigravity/mcp_config.json |
完整指南 |
| 光标 | ~/.cursor/mcp.json |
完整指南 |
| 帆板运动 | ~/.codeium/windsurf/mcp_config.json |
完整指南 |
| 克劳德桌面版 | ~/Library/Application Support/Claude/claude_desktop_config.json |
完整指南 |
| VS代码(副本) | .vscode/mcp.json |
完整指南 |
| 克莱恩 | cline_mcp_settings.json |
完整指南 |
| Continue.dev | .continue/mcpServers/ |
完整指南 |
| 泽德 | ~/.config/zed/settings.json |
完整指南 |
| 开源代码 | opencode.json |
完整指南 |
| MCP服务器助手 | aider-mcp 命令 |
完整指南 |
快速配置(反重力)
增添 ~/.gemini/antigravity/mcp_config.json:
{
"mcpServers": {
"opencode": {
"command": "node",
"args": ["/path/to/opencode-mcp/dist/index.js"],
"env": {
"OPENCODE_SERVER_URL": "http://localhost:4096",
"OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
}
}
}
}
注: 替换
/path/to/opencode-mcp使用克隆存储库的实际路径。
快速配置(光标)
增添 ~/.cursor/mcp.json:
{
"mcpServers": {
"opencode": {
"command": "node",
"args": ["/path/to/opencode-mcp/dist/index.js"],
"env": {
"OPENCODE_SERVER_URL": "http://localhost:4096",
"OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
}
}
}
}
快速配置(克劳德桌面)
增添 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"opencode": {
"command": "node",
"args": ["/path/to/opencode-mcp/dist/index.js"],
"env": {
"OPENCODE_SERVER_URL": "http://localhost:4096",
"OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
}
}
}
}
看 文档/设置指南/ 有关所有支持的IDE的完整设置说明。
可用工具(21)
执行(5)
| 工具 | 说明 |
|---|---|
opencode_run |
通过OpenCode执行编码任务 |
opencode_session_create |
创建新会话 |
opencode_session_prompt |
向会话发送提示 |
opencode_session_list |
列出所有会话 |
opencode_session_abort |
中止正在运行的会话 |
文件(4)
| 工具 | 说明 |
|---|---|
opencode_file_read |
从项目中读取文件 |
opencode_file_search |
在文件中搜索文本 |
opencode_find_files |
按名称/模式查找文件 |
opencode_find_symbols |
查找工作空间符号 |
配置(5)
| 工具 | 说明 |
|---|---|
opencode_model_list |
列出可用型号 |
opencode_model_configure |
配置模型选项 |
opencode_provider_list |
列出提供者 |
opencode_config_get |
获取配置 |
opencode_config_update |
更新配置 |
代理商(2)
| 工具 | 说明 |
|---|---|
opencode_agent_list |
列出可用代理 |
opencode_agent_delegate |
委派给代理人 |
技能(2)
| 工具 | 说明 |
|---|---|
opencode_skill_list |
列出可用技能 |
opencode_skill_create |
创造技能 |
MCP管理(2)
| 工具 | 说明 |
|---|---|
opencode_mcp_list |
列出MCP服务器 |
opencode_mcp_enable |
启用/禁用MCP服务器 |
工具配置(1)
| 工具 | 说明 |
|---|---|
opencode_tool_list |
列出所有工具 |
用法示例
基本任务执行
Use opencode_run to implement a React hook for fetching data with loading and error states
与规划代理进行代码审查
Use opencode_agent_delegate to have the plan agent review the authentication module for security issues
文件搜索
Use opencode_file_search to find all uses of deprecated functions
模型配置
Use opencode_model_configure to set reasoningEffort to high for deep thinking tasks
创造技能
Use opencode_skill_create to create a skill for database migration patterns
配置文件
该项目包括各种AI编码代理的预配置文件:
根级别配置文件
| 文件 | 格式 | 使用人 |
|---|---|---|
AGENTS.md |
通用 | Codex、Cursor、Gemini CLI、Claude Code、Windsurf、Zed、Cline |
CLAUDE.md |
克劳德代码 | 克劳德代码 |
.cursorrules |
纯文本 | 光标 |
.windsurfrules |
纯文本 | Windsurf |
.clinerules/rules.md |
Markdown | Cline |
.continue/rules/opencode.md |
YAML+Markdown | 继续开发 |
.github/copilot-instructions.md |
Markdown | GitHub副本 |
配置/目录
configs/
├── agents/
│ ├── AGENTS.md # Universal agent format
│ └── CLAUDE.md # Claude Code specific
├── skills/
│ └── SKILL.md # Agent Skills format (agentskills.io)
├── rules/
│ ├── cursor.md # Cursor rules
│ ├── continue.md # Continue rules (YAML frontmatter)
│ └── copilot-instructions.md
├── mcp/
│ └── templates.md # MCP config templates
└── README.md # Config documentation
代理技能格式(SKILL.md)
基于 agentskills.io 网站 规范:
---
name: skill-name
description: When to use this skill
---
# Instructions...
看 configs/README.md 有关安装说明。
运输方式
stdio(默认)
- 最适合本地IDE集成
- 单客户端连接
- 无需配置
超文本传输协议
- 最适合远程访问和多个客户端
- 支持无状态和有状态会话
- 使用环境变量进行配置:
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @opencode-mcp/server
端点:
| 端点 | 方法 | 描述 |
|---|---|---|
/health |
GET | 健康检查 |
/api |
获取 | API文档 |
/mcp |
POST | 无状态MCP请求 |
/mcp |
GET | SSE流媒体(无状态) |
/mcp/:sessionId |
POST | 有状态的MCP请求 |
/mcp/:sessionId |
GET | SSE流式传输(有状态) |
/mcp/:sessionId |
DELETE | 关闭有状态会话 |
模式:
- 无状态 (默认):请求之间没有会话状态,更有利于扩展
- 有状态的:通过sessionId维护会话状态,这是多回合上下文所必需的
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
OPENCODE_SERVER_URL |
http://localhost:4096 |
OpenCode服务器URL |
OPENCODE_AUTO_START |
true |
自动启动OpenCode |
OPENCODE_DEFAULT_MODEL |
- | 默认型号 |
OPENCODE_TIMEOUT |
120000 |
请求超时(毫秒) |
OPENCODE_DEFAULT_PROJECT |
- | 默认项目目录(未指定工作目录时使用) |
OPENCODE_CONFIG_PATH |
自动检测 | 用于配置持久性的opencode.json路径 |
OPENCODE_LOG_LEVEL |
info |
日志级别(调试、信息、警告、错误、无) |
OPENCODE_LOG_TIMESTAMP |
false |
在日志中包含时间戳 |
MCP_TRANSPORT |
stdio |
传输模式(stdio或http) |
MCP_HTTP_PORT |
3000 |
HTTP端口 |
MCP_CORS_ORIGINS |
* |
CORS起源(逗号分隔,生产中限制) |
配置持久性
配置工具(opencode_model_configure, opencode_config_update)使用a 混合方法:
- API更新 -更改将立即应用于正在运行的OpenCode服务器
- 文件持久性 -更改已保存到
opencode.json用于跨重启的持久性
配置路径检测
配置文件位置在此优先级中自动检测:
OPENCODE_CONFIG_PATH环境变量(显式覆盖)- 项目本地:
{workingDirectory}/.opencode/opencode.json - 全球:
~/.config/opencode/opencode.json
更改与现有配置深度合并,保留其他设置。
项目目录检测
OpenCode MCP服务器使用此优先级来确定工作目录:
- 明确的
workingDirectory参数 -传入工具调用 OPENCODE_DEFAULT_PROJECT环境变量 -在MCP配置中设置- 自动检测 -搜索
.git,package.json,等从当前目录 - 后备方案 -MCP服务器进程的当前工作目录
推荐: 集 OPENCODE_DEFAULT_PROJECT 在MCP配置中,避免每次都指定目录:
{
"mcpServers": {
"opencode": {
"command": "node",
"args": ["/path/to/opencode-mcp/dist/index.js"],
"env": {
"OPENCODE_SERVER_URL": "http://localhost:4096",
"OPENCODE_DEFAULT_PROJECT": "/path/to/your/project"
}
}
}
}
错误处理
所有工具都以一致的格式返回错误,并提供可操作的建议:
Error: <operation> failed.
Details: <error message>
Suggestions:
1. <actionable suggestion>
2. <another suggestion>
看 错误处理指南 了解详情。
发展
# Clone and install
git clone https://github.com/opencode-mcp/server.git
cd server
npm install
# Run in dev mode
npm run dev
# Run tests
npm test
# Run linting
npm run lint
# Build
npm run build
安全
OpenCode MCP服务器的设计考虑了安全性:
- stdio传输(默认):仅限本地访问,需要系统访问权限
- 无凭据存储:由OpenCode管理的API密钥,而不是MCP服务器
- 输入验证:所有输入均已Zod模式验证
- CORS可配置:限制HTTP传输的来源
- 请求限制:可配置的车身尺寸限制和超时
有关使用HTTP传输的生产部署,请参阅 安全指南.
文档
贡献
欢迎投稿!请阅读我们的 贡献指南 了解详情。
许可证
MIT许可证-请参阅 许可证 了解详情。
致谢
- 开源代码 -此服务器集成的AI编码代理
- 模型上下文协议 -使这成为可能的协议
- MCP TypeScript SDK -用于构建此服务器的SDK