opencode_native_tools
This server provides a comprehensive set of MCP tools mirroring OpenCode 1.18.9, usable by any MCP client (e.g., Codex, Claude Code). Capabilities include:
File Operations: Read files/directories with pagination and attachment support (images/PDFs), write files, perform contextual edits, and apply structured OpenCode patches for add/delete/update/move.
Search: Glob for filename patterns, grep for content with regex and file type filtering.
Shell: Execute shell commands (bash) with configurable working directory, timeout, and output handling.
Web: Fetch web page content in text/markdown/HTML, and search the web via Exa or Parallel.
Todos: Manage session-isolated task lists with status and priority.
Skills: Load specialized skill instructions from various sources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opencode_native_tools Find all TODO comments in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenCode Native Tools MCP
一个独立的 MCP stdio Server,把 OpenCode 1.18.9 的公开内置工具带给 Codex、Claude Code 和其他 MCP Code CLI。
它不启动、不调用、也不依赖本机 opencode CLI。
工具
工具 | 用途 |
| 紧凑读取文件、目录、图片和 PDF;支持分页、截断、批量读取和二进制识别 |
| 文件搜索与紧凑内容搜索 |
| 写入、上下文编辑和 OpenCode patch |
| Shell 命令、超时、输出截断和进程树清理 |
| 网页读取,以及 Exa / Parallel 搜索 |
| 连接隔离、可持久化的待办列表 |
| OpenCode、Claude、项目和 URL Skill 发现 |
task、question、lsp、OpenCode UI ask、插件 hooks 和内部控制工具不包含在内,因为它们依赖 OpenCode 的交互界面、子代理、LSP 会话或插件运行时。
Related MCP server: openai-agents-mcp
紧凑输出
read 默认只返回带行号的正文;grep 默认返回 文件:行号:内容。两者不会再把正文复制到 preview 或 display.text。读取被截断时,正文末尾会给出 startLine、endLine、totalLines 和 nextOffset;受字节上限影响而无法确认总行数时,totalLines=unknown。
需要机器可读元数据时传入 responseFormat: "detailed"。此时 structuredContent 只包含分页或匹配统计字段,不会重复正文。readMany 最多读取 8 个文件,默认每个文件 200 行,整批输出最多 100 KB;单个文件失败会作为该文件的结果返回,不会中断其他文件。
readMany 只接受文本文件;目录、图片和 PDF 会返回单项错误,必须通过 read 读取。取消请求会终止整个批次,不会伪装成成功返回的文件错误。
搜索输出与分页
grep 保留原来的默认 content 模式,并提供 outputMode: "files_with_matches"(只返回文件路径)和 outputMode: "count"(返回每个文件的匹配行数,不是匹配子串次数)。只需要定位文件时,选择路径模式可避免输出无用正文。
{
"pattern": "TODO",
"include": "**/*.ts",
"outputMode": "files_with_matches",
"limit": 50,
"offset": 0,
"responseFormat": "detailed"
}结果按路径排序,limit 为每页输出条目数(默认 100,范围 1–1000),offset 从 0 开始。nextOffset 非空时,用它读取下一页;文件变化时,跨请求分页不是固定快照。输出最多 50 KB,提前达到字节上限时同样提供可继续使用的 nextOffset。
ignoreCase: true 开启大小写不敏感搜索;context 为内容模式的前后上下文行数(0–20)。匹配行使用 路径:行号:正文,上下文行使用 路径-行号-正文;分页单位是输出条目,包括上下文行。
搜索的数量限制只统计实际输出条目,不统计 ripgrep 的生命周期记录。搜索超时为 30 秒;取消或截断时,会等待子进程退出并释放取消监听器。对存在的单个文件指定 path 时,只搜索该文件;为兼容原有行为,不存在的文件路径仍搜索其父目录。
工具目录提供标准 MCP annotations,区分只读、潜在破坏性、幂等和外部访问行为。注解只供宿主参考,不能代替批准或路径权限检查。
安装到 Codex
需要 Node.js 20 或更高版本。选择以下任一种方式;通常推荐 方式 A,它启动更快且不依赖每次执行时下载包。
方式 A:全局安装
npm install -g opencode-native-tools-mcp在 Codex 配置文件中加入:
[mcp_servers.opencode_native_tools]
command = "opencode-native-tools"
args = []
startup_timeout_sec = 30.0默认情况下,服务使用 MCP Client 启动它时的工作目录作为项目根目录。
方式 B:使用 npx,不做全局安装
不需要先执行 npm install -g。在 Codex 配置文件中加入:
[mcp_servers.opencode_native_tools]
command = "npx"
args = ["-y", "opencode-native-tools-mcp@latest"]
startup_timeout_sec = 30.0安装 MCP 后,建议执行一次配置器,让 Codex 自动优先使用本服务进行读取和搜索:
opencode-native-tools apply
opencode-native-tools status如果使用的是本节的 npx 方式,执行 npx -y opencode-native-tools-mcp@latest apply。apply 会保留已有 MCP 的 command 和 args,并更新全局 AGENTS.md 中的标记块。它不会把本 MCP 加入 direct_only_tool_namespaces:文件修改必须交给 Codex 原生的 write / edit / apply_patch,这样 Codex 才能显示文件修改 Diff。完成后重启 Codex 或新建 task。需要撤销自动规则时执行 opencode-native-tools unapply。
默认情况下,服务使用 MCP Client 启动它时的工作目录作为项目根目录。
如果需要固定操作某个项目,再额外添加:
[mcp_servers.opencode_native_tools.env]
OPENCODE_TOOLS_ROOT = "D:/path/to/your-project"Windows 的全局 Codex 配置文件通常是:
C:\Users\<你的用户名>\.codex\config.toml保存后重启 Codex Desktop,或新建一个 task,让 Codex 重新读取 MCP 配置。
验证是否接入成功
在终端执行:
codex mcp list应该能看到:
opencode_native_tools ... enabled然后在新的 Codex task 中输入:
使用 opencode_native_tools 的 glob 查找 package.json,再用 read 读取它。Codex 应调用 read、glob、grep、write、edit、apply_patch、bash 等同名 MCP 工具。
MCP 资源与文件读取
resources/read 和 read 工具是不同接口。读取项目文件时,调用 read 或 readMany 工具并传入 filePath,不要把文件路径作为资源 URI。
服务支持 resources/list、resources/templates/list 和 resources/read,并在初始化时声明资源能力。资源列表只提供 opencode-tools://status,返回服务诊断信息;为兼容已有诊断探测,test 也可作为这个资源的别名。未知资源返回带引导说明的成功结果(提示改用 read / readMany 工具读文件),而不是 -32002 错误——部分宿主(如 Codex 桌面端 0.151+)会把 read_mcp_resource 暴露给模型,模型用编造的 URI 反复探测时,错误应答只会让它原样重试;缺少或无效的 uri 仍返回 -32602。
诊断资源是可选的,不需要在每次读取或搜索文件前调用,也不应反复探测。旧版出现 resources/read ... Method not found 时,更新包并重启 MCP 连接;再次运行 apply 可更新全局 AGENTS.md 中的调用说明。
项目根目录
OPENCODE_TOOLS_ROOT 用于固定该 MCP 默认操作的项目目录。未设置时,服务使用 MCP Client 启动时的工作目录;只有在全局配置需要固定到某个仓库时,才需要设置它。
如果不设置它,服务会使用 Codex 启动 MCP 进程时的工作目录。
权限与禁用工具
OpenCode 的 ask 是其自身 UI 的交互能力,通用 MCP Server 无法复刻。文件修改和 shell 命令的批准应由 Codex 在调用前负责。
推荐为有副作用的工具要求批准:
[mcp_servers.opencode_native_tools.tools.write]
approval_mode = "approve"
[mcp_servers.opencode_native_tools.tools.edit]
approval_mode = "approve"
[mcp_servers.opencode_native_tools.tools.apply_patch]
approval_mode = "approve"
[mcp_servers.opencode_native_tools.tools.bash]
approval_mode = "approve"可以禁用不希望 Codex 使用的工具:
[mcp_servers.opencode_native_tools]
disabled_tools = ["bash", "webfetch", "websearch"]或者只保留白名单中的工具:
[mcp_servers.opencode_native_tools]
enabled_tools = ["read", "glob", "grep", "write", "edit", "apply_patch"]这些是 Codex 的 MCP 配置,只影响 Codex;其他 MCP Client 仍会看到服务公开的完整工具列表。
apply_patch 的目标路径位于 patchText 中。宿主应在调用前解析 *** Add File、*** Update File、*** Delete File 和 *** Move to,并按自身策略批准工作区外访问。结果中的 metadata.externalPaths 用于审计,不能替代调用前批准。
让 Codex 优先使用本 MCP
服务会在 MCP 初始化时声明对文件读取和搜索的工具偏好。文件修改使用 Codex 原生工具,以便 Codex 记录并显示文件 Diff。要让 Codex 在项目中更稳定地优先使用本 MCP,可以在目标仓库根目录放置 AGENTS.md。
仓库提供了可直接使用的模板:templates/AGENTS.md。它要求 Codex 使用 opencode_native_tools 进行读取和搜索,并使用 Codex 原生编辑工具修改文件,以保留 Codex 的 Diff 展示。
搜索与可选依赖
glob 和 grep 优先使用系统 PATH 中的 rg。找不到时,服务会下载兼容版本的 ripgrep 并写入自己的缓存;普通用户通常不需要手动安装 rg。离线或受限网络环境可以自行安装 ripgrep,或设置:
OPENCODE_TOOLS_RG_PATH=/path/to/rgWindows 下服务会按 PATH 优先级查找 rg.exe,但会跳过 Codex Desktop WindowsApps 中不可由 MCP 启动的内置副本。其他候选和缓存副本会在服务首次使用时验证一次可执行性;成功路径会在进程内缓存,后续 glob 和 grep 不产生额外探测开销。
没有可用的 ripgrep 时,服务会下载并验证自己的缓存版本。受限网络环境可通过 OPENCODE_TOOLS_RG_PATH 指定允许启动的 rg.exe 绝对路径。
websearch 是可选工具。要启用它,在 MCP 的 env 中提供一个 provider 的 key:
[mcp_servers.opencode_native_tools.env]
EXA_API_KEY = "..."
# 或 PARALLEL_API_KEY = "..."可通过 OPENCODE_WEBSEARCH_PROVIDER = "exa" 或 "parallel" 固定 provider。Parallel 还可设置 OPENCODE_TOOLS_MODEL_NAME。
OpenCode 兼容配置
服务会读取兼容的 OpenCode JSON / JSONC 配置数据,但不会加载 OpenCode runtime、插件或 hooks。支持以下配置来源:
OPENCODE_CONFIGOPENCODE_CONFIG_CONTENTOPENCODE_CONFIG_DIROPENCODE_DISABLE_PROJECT_CONFIG
兼容 shell、tool_output、formatter、skills 和 websearch runtime flags。Windows 默认按 pwsh、powershell、Git Bash、cmd 选择 shell;OPENCODE_TOOLS_SHELL 和 OPENCODE_GIT_BASH_PATH 可覆盖。
默认不会格式化文件。要在 write、edit、apply_patch 后启用 formatter,在项目的 opencode.json 或 opencode.jsonc 中设置:
{
"formatter": true
}兼容性边界
本实现以 OpenCode 1.18.9 为固定对照基线。以下差异是通用 MCP 协议限制或有意保留的独立实现选择:
宿主 Code CLI 负责批准;不提供 OpenCode UI
ask。LSP diagnostics、watcher 和 OpenCode event bus 未迁移。
标准 MCP
content/structuredContent是对 OpenCode 内部 Tool result 的协议适配。apply_patch会先计算全部变更,再原子提交;OpenCode 原实现为审批后按顺序应用。ripgrep、formatter、URL skills 和 shell 输出使用本服务的独立缓存,不与 OpenCode 全局缓存共享。
Available Tools
11 toolsapply_patchA
Apply an OpenCode patch document. Wrap one or more file operations in *** Begin Patch and *** End Patch. Use *** Add File, *** Delete File, or *** Update File headers. New lines in an added file must begin with +. Updates may include a *** Move to: path directive.
Inputs: patchText (required).
bashA
Execute a shell command. Set workdir instead of changing directories inside the command when possible. timeout is in milliseconds. Output is capped; complete truncated output is saved to a file.
Inputs: command (required), timeout, workdir.
editA
Replace text in a file using OpenCode matching semantics. Preserve the exact indentation from read output, excluding its line-number prefix. The operation fails when oldString cannot be identified unambiguously; supply more context or use replaceAll to replace every occurrence.
Inputs: filePath (required), newString (required), oldString (required), replaceAll.
globA
Fast file pattern matching for codebases of any size. Supports patterns such as /*.js and src//*.ts. Returns matching file paths. Use it to find files by name pattern.
Inputs: pattern (required), path.
grepA
Fast regular-expression content search for codebases of any size. The optional include parameter filters searched files, for example *.js or *.{ts,tsx}. Returns matching paths, line numbers, and matching lines.
Inputs: pattern (required), path, include.
readA
Read a file or directory from the local filesystem. The filePath should be absolute. By default, returns up to 2000 lines starting at line 1. Use offset (1-indexed) and limit to read later sections. Lines are returned as : ; directories list entries with a trailing / for subdirectories. Lines longer than 2000 characters are truncated. Images and PDFs are returned as attachments.
Inputs: filePath (required), limit, offset.
skillA
Load a discovered specialized skill. The output contains the skill instructions and references to files in the skill directory. The name must match a discovered skill.
Inputs: name (required).
todowriteB
Create and maintain the structured task list for the current MCP session. Each item has content, status, and priority.
Inputs: todos (required).
webfetchA
Fetch content from a fully formed HTTP or HTTPS URL. format controls whether text, Markdown, or HTML is returned; Markdown is the default. This tool is read-only.
Inputs: url (required), format, timeout.
websearchA
Search the web through the configured Exa or Parallel provider. Query is required; numResults, livecrawl, type, and contextMaxCharacters are optional provider controls.
Inputs: query (required), type, livecrawl, numResults, +1 more.
writeA
Write a text file to the local filesystem. An existing file is overwritten. Prefer edit for an existing file when a targeted replacement is sufficient.
Inputs: content (required), filePath (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes: read vs. write vs. edit are separated by whole-file vs. targeted replacement, and webfetch vs. websearch are cleanly split. However, write, edit, apply_patch, and bash all touch file modification, which could cause occasional misselection.
Names use a mix of single verbs (read, write, edit, glob, grep), compound words (webfetch, websearch, todowrite), a proper command (bash), and one underscored verb_noun (apply_patch). This is readable but lacks a uniform pattern.
With 11 tools, the set is well-scoped for a coding assistant: it covers file operations, search, shell execution, web access, task tracking, and skill loading without being bloated or sparse.
The file lifecycle is complete (create via write, read, update via edit/apply_patch, delete/move via apply_patch), and search, shell, web, task management, and skill loading cover the expected capabilities for a native tool server. No obvious critical gaps.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal MCP server that wraps the headless Claude Code CLI as MCP tools, providing stateless access to Claude's coding capabilities through prompt-based interactions. It enables users to execute Claude Code commands with various prompt formats and structured outputs directly from MCP clients.3MIT
- AlicenseAqualityDmaintenanceMCP server that bridges OpenAI's Agents SDK with Claude Code, enabling web search, file search, and computer use capabilities directly in your development environment.29 npm1MIT
- AlicenseNot gradedqualityCmaintenanceA Model Context Protocol (MCP) server that enables remote access to OpenCode AI coding agent, allowing MCP-compatible clients to leverage OpenCode's capabilities.MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that lets an AI coding agent delegate implementation work to the OpenCode CLI, choosing an explicit provider + model on every call.3MIT