opencode-mcp
Allows asking natural-language questions about a GitHub repository and receiving answers grounded in the code.
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-mcp Where is the main entry point in facebook/react?"
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.
DEPRECATED
This project is deprecated and no longer maintained.
opencode-mcp
MCP server (stdio) exposing an ask_codebase tool: ask a natural-language question about a GitHub repository, get an answer grounded in the real code. READ-ONLY by design.
Built in TypeScript on the official MCP TypeScript SDK, and on opencode running headless as the analysis engine.
How it works
The server fetches the repo itself — clone if absent, fetch + hard resync otherwise. Fully deterministic: a nonexistent repo fails in seconds with the git error relayed verbatim, zero LLM tokens spent.
opencode runs headless with
cwd= the repo directory. Noopencode serve, no--attach. The repo's ownAGENTS.md(if any) is loaded as project context. Sessions are opencode-native and scoped per project directory, socontinue_session=truedeterministically means "the latest session of this repo" — cross-repo cross-talk is impossible by construction.
Fetch policy
A clone/fetch runs only when:
the repo is not in the manifest, or
its checkout is missing on disk (periodic cleanup), or
an explicitly requested branch differs from the checked-out one, or
the last fetch is older than
OPENCODE_REPO_TTL_DAYS(default 3).
Otherwise the existing checkout is used as-is, so the code stays stable across follow-up calls.
Manifest
Known checkouts are tracked in .opencode_mcp_manifest.json (atomic writes, one entry per owner/repo):
{
"owner/repo": {
"dir": "/abs/path",
"branch": "main",
"fetched_at": "2026-07-15T03:21:00Z"
}
}Read-only enforcement
Two layers:
A read-only preamble injected into every prompt by this server.
Your opencode agent config — define an "explore"-style agent with
edit: denyand setOPENCODE_AGENTto force it on every run.
Do not put read-only rules in your global AGENTS.md: it would poison your normal interactive opencode sessions.
Long calls
The hard timeout defaults to 10 minutes and an MCP progress notification is emitted every 15 s (clone/fetch included). Per the MCP spec, clients that reset their request timeout on progress keep the call alive; when the client sends no progressToken, the heartbeat is a no-op. Align the client's own per-call timeout (timeout: in the mcp_servers entry) above the hard one.
Related MCP server: Company Docs MCP Server
Requirements
Node.js ≥ 20
giton the PATHopencode CLI (absolute path recommended via
OPENCODE_BIN)
Install
From npm:
npm install -g @mvagnon/opencode-mcp # installs the `opencode-mcp` commandOr run it without installing:
npx -y @mvagnon/opencode-mcpFrom source:
npm install
npm run build # server binary: dist/index.js (stdio transport)Configuration
Declare environment variables in the env: block of the client's mcp_servers entry. Hermes does not pass your full shell env to stdio servers — only PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR.
Variable | Default | Purpose |
|
| opencode binary (absolute path recommended) |
| (none) | opencode agent forced on every run (e.g. |
|
| Where checkouts live |
|
| Directory of |
|
| Re-fetch a repo after this many days |
|
| Hard timeout for the opencode run, in seconds |
Example client entry (Hermes):
mcp_servers:
opencode:
command: npx
args: ["-y", "@mvagnon/opencode-mcp"]
timeout: 660 # keep above ASK_CODEBASE_TIMEOUT
env:
OPENCODE_BIN: /usr/local/bin/opencode
OPENCODE_AGENT: exploreFor a from-source checkout, use command: node with args: ["/abs/path/to/opencode-mcp/dist/index.js"] instead.
The ask_codebase tool
Argument | Type | Description |
|
| The natural-language question (e.g. "where is API request auth validated?") |
|
| Exact GitHub slug |
|
| Optional branch to pin; omit for the default branch |
|
| Resume the latest discussion of this repo (default |
Use it for architecture questions, where a feature lives, request flow, conventions, design rationale, etc.
Development
npm run lint # eslint
npm run typecheck # tsc --noEmit
npm run build # emit dist/
npm test # node:test unit tests (pure logic)
npm run dev # tsc --watchSource layout: see AGENTS.md.
Releasing
Releases are fully automated with release-please and npm trusted publishing (OIDC — no npm token stored in the repo):
Land changes on
mainusing Conventional Commits (feat:,fix:,feat!:…) — they drive the version bump and the changelog.release-please maintains a release PR that accumulates changes, bumps
package.json, and updatesCHANGELOG.md.Merging the release PR creates the GitHub release and tag; the
publishjob then publishes to npm via OIDC.
One-time setup (already done once the package exists):
npm cannot create a package via OIDC, so the first version must be published manually (
npm login && npm publish).Then on npmjs.com → package → Settings → Trusted Publisher: GitHub Actions, repository
mvagnon/opencode-mcp, workflowrelease.yml.
Available Tools
1 toolask_codebaseAsk codebaseARead-only
Ask a natural-language question about a GitHub repository and get an answer grounded in the real code. READ-ONLY: never writes, edits, builds, or executes anything. The harness fetches the repo itself (clone or refresh, max every few days) — a nonexistent repo fails fast with the exact git error. Stateful PER REPOSITORY: continue_session=true resumes the latest discussion of that owner/repo (follow-up questions keep their context); false (default) starts a fresh one. Optional branch pins a specific branch. Use it for architecture questions, where a feature lives, request flow, conventions, design rationale, etc.
Inputs: repo (required), question (required), branch, continue_session.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clearly defined as read-only codebase Q&A.
The single tool name 'ask_codebase' follows a clear verb_noun pattern, which is consistent and descriptive.
One tool feels thin for a general-purpose MCP server, but it is appropriately focused for a specialized read-only Q&A assistant. The count is borderline but acceptable.
The tool covers the entire stated domain of asking questions about a codebase, with session state, branch selection, and error handling. No obvious gaps for its intended purpose.
Maintenance
Related MCP Connectors
Ask any GitHub repository a question. Get source-backed answers.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to access live GitHub repository data without cloning, supporting repo summarization, file explanation, recent changes, and dependency analysis.12 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceProvides read-only access to company GitHub repositories, enabling code search, file retrieval, documentation search, and repo browsing via natural language.-
- AlicenseNot gradedqualityDmaintenanceEnables interacting with GitHub repositories for pull requests, code, and reviews through natural language.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to answer natural-language GitHub queries by listing repositories, issues, pull requests, branches, commits, and files, as well as performing writes with dry-run and confirmation safeguards.-