OpenCode MCP Server

MCP server that exposes OpenCode as a tool/subagent for IDEs and AI clients

Overview

OpenCode MCP Server allows any MCP-compatible client (Cursor, Windsurf, Claude Desktop, Claude Code, Opencode, Antigravity, Zed, etc.) to delegate coding tasks to OpenCode as a subagent. This enables powerful multi-tool workflows where your primary AI assistant can call upon OpenCode for:

Code implementation and refactoring
File operations and search
Code analysis and planning
Multi-turn coding sessions
Agent delegation (build, plan, custom agents)
Model and provider management
Skill discovery and creation
Sub-MCP server management

Features

Full OpenCode Integration: Access all OpenCode capabilities via MCP tools
21 Tools: Streamlined toolset for coding, config, agents, skills, and MCP management
Hybrid Config Persistence: Config changes apply immediately AND persist to opencode.json
Tool Annotations: MCP-compliant annotations for better LLM discoverability
Dual Transport: stdio (local) and HTTP (remote) with stateless/stateful modes
Type-Safe: Full TypeScript support with Zod v4 validation
Actionable Errors: Error messages include specific suggestions for resolution
Request Timeouts: Configurable timeout handling with proper cleanup
Structured Logging: Debug, info, warn, error levels via environment variable
Session Management: Create and manage coding sessions
Agent Delegation: Delegate tasks to specialized agents (build, plan, explore)
Skill System: Discover and create reusable skill definitions
MCP Management: List and enable/disable MCP servers

Quick Start

Installation

# 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

Prerequisites

OpenCode installed: Install OpenCode
OpenCode server running: Start with opencode serve or the TUI
API keys configured: Set up your LLM provider keys in OpenCode
This MCP server built: Run npm run build in the project directory

Configure in Your IDE

OpenCode MCP Server works with all major AI-enabled IDEs:

IDE	Config File	Setup Guide
Codex CLI	`~/.codex/config.toml`	Full Guide
Gemini CLI	`~/.gemini/settings.json`	Full Guide
Roo Code	`mcp_settings.json` or `.roo/mcp.json`	Full Guide
Antigravity	`~/.gemini/antigravity/mcp_config.json`	Full Guide
Cursor	`~/.cursor/mcp.json`	Full Guide
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Full Guide
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	Full Guide
VS Code (Copilot)	`.vscode/mcp.json`	Full Guide
Cline	`cline_mcp_settings.json`	Full Guide
Continue.dev	`.continue/mcpServers/`	Full Guide
Zed	`~/.config/zed/settings.json`	Full Guide
OpenCode	`opencode.json`	Full Guide
Aider MCP Server	`aider-mcp` command	Full Guide

Quick Config (Antigravity)

Add to ~/.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"
      }
    }
  }
}

Note: Replace /path/to/opencode-mcp with the actual path where you cloned the repository.

Quick Config (Cursor)

Add to ~/.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"
      }
    }
  }
}

Quick Config (Claude Desktop)

Add to ~/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"
      }
    }
  }
}

See docs/setup-guides/ for complete setup instructions for all supported IDEs.

Available Tools (21)

Execution (5)

Tool	Description
`opencode_run`	Execute a coding task through OpenCode
`opencode_session_create`	Create a new session
`opencode_session_prompt`	Send a prompt to a session
`opencode_session_list`	List all sessions
`opencode_session_abort`	Abort a running session

Files (4)

Tool	Description
`opencode_file_read`	Read a file from the project
`opencode_file_search`	Search text in files
`opencode_find_files`	Find files by name/pattern
`opencode_find_symbols`	Find workspace symbols

Config (5)

Tool	Description
`opencode_model_list`	List available models
`opencode_model_configure`	Configure model options
`opencode_provider_list`	List providers
`opencode_config_get`	Get configuration
`opencode_config_update`	Update configuration

Agents (2)

Tool	Description
`opencode_agent_list`	List available agents
`opencode_agent_delegate`	Delegate to an agent

Skills (2)

Tool	Description
`opencode_skill_list`	List available skills
`opencode_skill_create`	Create a skill

MCP Management (2)

Tool	Description
`opencode_mcp_list`	List MCP servers
`opencode_mcp_enable`	Enable/disable MCP server

Tool Config (1)

Tool	Description
`opencode_tool_list`	List all tools

Usage Examples

Basic Task Execution

Use opencode_run to implement a React hook for fetching data with loading and error states

Code Review with Planning Agent

Use opencode_agent_delegate to have the plan agent review the authentication module for security issues

File Search

Use opencode_file_search to find all uses of deprecated functions

Model Configuration

Use opencode_model_configure to set reasoningEffort to high for deep thinking tasks

Create a Skill

Use opencode_skill_create to create a skill for database migration patterns

Configuration Files

This project includes pre-configured files for various AI coding agents:

Root-Level Config Files

File	Format	Used By
`AGENTS.md`	Universal	Codex, Cursor, Gemini CLI, Claude Code, Windsurf, Zed, Cline
`CLAUDE.md`	Claude Code	Claude Code
`.cursorrules`	Plain text	Cursor
`.windsurfrules`	Plain text	Windsurf
`.clinerules/rules.md`	Markdown	Cline
`.continue/rules/opencode.md`	YAML+Markdown	Continue.dev
`.github/copilot-instructions.md`	Markdown	GitHub Copilot

configs/ Directory

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

Agent Skills Format (SKILL.md)

Based on agentskills.io specification:

---
name: skill-name
description: When to use this skill
---

# Instructions...

See configs/README.md for installation instructions.

Transport Modes

stdio (Default)

Best for local IDE integration
Single client connection
No configuration needed

HTTP

Best for remote access and multiple clients
Supports stateless and stateful sessions
Configure with environment variables:

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @opencode-mcp/server

Endpoints:

Endpoint	Method	Description
`/health`	GET	Health check
`/api`	GET	API documentation
`/mcp`	POST	Stateless MCP requests
`/mcp`	GET	SSE streaming (stateless)
`/mcp/:sessionId`	POST	Stateful MCP requests
`/mcp/:sessionId`	GET	SSE streaming (stateful)
`/mcp/:sessionId`	DELETE	Close stateful session

Modes:

Stateless (default): No session state between requests, better for scaling
Stateful: Session state maintained via sessionId, required for multi-turn context

Environment Variables

Variable	Default	Description
`OPENCODE_SERVER_URL`	`http://localhost:4096`	OpenCode server URL
`OPENCODE_AUTO_START`	`true`	Auto-start OpenCode
`OPENCODE_DEFAULT_MODEL`	-	Default model
`OPENCODE_TIMEOUT`	`120000`	Request timeout in ms
`OPENCODE_DEFAULT_PROJECT`	-	Default project directory (used when workingDirectory not specified)
`OPENCODE_CONFIG_PATH`	auto-detected	Path to opencode.json for config persistence
`OPENCODE_LOG_LEVEL`	`info`	Log level (debug, info, warn, error, none)
`OPENCODE_LOG_TIMESTAMP`	`false`	Include timestamps in logs
`MCP_TRANSPORT`	`stdio`	Transport mode (stdio or http)
`MCP_HTTP_PORT`	`3000`	HTTP port
`MCP_CORS_ORIGINS`	`*`	CORS origins (comma-separated, restrict in production)

Config Persistence

Config tools (opencode_model_configure, opencode_config_update) use a hybrid approach:

API Update - Changes apply immediately to the running OpenCode server
File Persistence - Changes are saved to opencode.json for persistence across restarts

Config Path Detection

The config file location is auto-detected in this priority:

OPENCODE_CONFIG_PATH environment variable (explicit override)
Project local: {workingDirectory}/.opencode/opencode.json
Global: ~/.config/opencode/opencode.json

Changes are deep-merged with existing config, preserving other settings.

Project Directory Detection

OpenCode MCP Server uses this priority to determine the working directory:

Explicit workingDirectory parameter - passed in tool call
OPENCODE_DEFAULT_PROJECT environment variable - set in MCP config
Auto-detection - searches for .git, package.json, etc. from current directory
Fallback - current working directory of MCP server process

Recommended: Set OPENCODE_DEFAULT_PROJECT in your MCP config to avoid specifying the directory every time:

{
  "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 Handling

All tools return errors in a consistent format with actionable suggestions:

Error: <operation> failed.

Details: <error message>

Suggestions:
  1. <actionable suggestion>
  2. <another suggestion>

See Error Handling Guide for details.

Development

# 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

Security

OpenCode MCP Server is designed with security in mind:

stdio transport (default): Local-only access, requires system access
No credential storage: API keys managed by OpenCode, not MCP server
Input validation: All inputs validated with Zod schemas
CORS configurable: Restrict origins for HTTP transport
Request limits: Configurable body size limits and timeouts

For production deployments with HTTP transport, see the Security Guide.

Documentation

API Reference - Complete tool documentation with annotations
IDE Setup Guide - Configure your IDE
Logging Guide - Configure logging levels
Error Handling Guide - Error format and categories
Security Guide - Security considerations and best practices
Architecture - System design

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Acknowledgments

OpenCode - The AI coding agent this server integrates
Model Context Protocol - The protocol that makes this possible
MCP TypeScript SDK - The SDK used to build this server

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.claude/skills/opencode-mcp		.claude/skills/opencode-mcp
.clinerules		.clinerules
.continue/rules		.continue/rules
.github		.github
configs		configs
docs		docs
src		src
tests		tests
.cursorrules		.cursorrules
.env.example		.env.example
.gitignore		.gitignore
.roorules		.roorules
.rules		.rules
.windsurfrules		.windsurfrules
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

OpenCode MCP Server

Overview

Features

Quick Start

Installation

Prerequisites

Configure in Your IDE

Quick Config (Antigravity)

Quick Config (Cursor)

Quick Config (Claude Desktop)

Available Tools (21)

Execution (5)

Files (4)

Config (5)

Agents (2)

Skills (2)

MCP Management (2)

Tool Config (1)

Usage Examples

Basic Task Execution

Code Review with Planning Agent

File Search

Model Configuration

Create a Skill

Configuration Files

Root-Level Config Files

configs/ Directory

Agent Skills Format (SKILL.md)

Transport Modes

stdio (Default)

HTTP

Environment Variables

Config Persistence

Config Path Detection

Project Directory Detection

Error Handling

Development

Security

Documentation

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages