OpenCode MCP Server

An MCP (Model Context Protocol) server that provides seamless integration with OpenCode, the open-source AI coding agent for the terminal.

Features

• Execute OpenCode Commands: Run any OpenCode CLI command programmatically
• Session Management: Create, continue, and export coding sessions
• Model Discovery: List available AI models from all configured providers
• Async Execution: Non-blocking command execution with timeout handling
• JSON Lines Parsing: Robust parsing of OpenCode's streaming output format

Tools Available

Tool	Description
execute_opencode_command	Execute any OpenCode CLI command with full flexibility
opencode_run	Run OpenCode with a simple prompt message
opencode_continue_session	Continue an existing OpenCode session
opencode_list_models	List available models, optionally filtered by provider
opencode_export_session	Export session data as JSON
opencode_get_status	Check OpenCode CLI availability and status

Installation

Prerequisites

• Python 3.10+
• OpenCode CLI installed and configured
• MCP-compatible client (Claude Desktop, etc.)

Install Dependencies

pip install -r requirements.txt

Configure MCP Client

Add to your MCP client configuration (e.g., ~/.claude.json or Claude Desktop settings):

{
  "mcpServers": {
    "opencode": {
      "command": "python",
      "args": ["-m", "src.services.fast_mcp.opencode_server"],
      "cwd": "/path/to/opencode-mcp"
    }
  }
}

Usage

Basic Usage

Once configured, the MCP tools are available through your MCP client:

# Run a coding task
opencode_run(message="Create a Python function that calculates fibonacci numbers")

# List available models
opencode_list_models(provider="anthropic")

# Continue a previous session
opencode_continue_session(session_id="abc123", message="Now add unit tests")

# Check status
opencode_get_status()

Tool Parameters

execute_opencode_command

{
    "prompt": str,           # Required: The prompt/task for OpenCode
    "model": str,            # Optional: Model in provider/model format (e.g., "anthropic/claude-sonnet-4-20250514")
    "agent": str,            # Optional: Agent to use (e.g., "build", "plan")
    "session": str,          # Optional: Session ID to continue
    "continue_session": bool, # Optional: Whether to continue last session
    "timeout": int           # Optional: Timeout in seconds (default: 300, max: 600)
}

opencode_run

{
    "message": str,     # Required: Message/prompt to send
    "model": str,       # Optional: Model to use
    "agent": str,       # Optional: Agent to use
    "files": [str],     # Optional: Files to attach
    "timeout": int      # Optional: Timeout in seconds
}

opencode_continue_session

{
    "session_id": str,  # Required: Session ID to continue
    "message": str,     # Optional: Follow-up message
    "timeout": int      # Optional: Timeout in seconds
}

Configuration

Environment variables (prefix: OPENCODE_):

Variable	Default	Description
OPENCODE_COMMAND	opencode	Path to OpenCode CLI
OPENCODE_DEFAULT_MODEL	None	Default model to use
OPENCODE_DEFAULT_AGENT	None	Default agent to use
OPENCODE_DEFAULT_TIMEOUT	300	Default timeout (seconds)
OPENCODE_MAX_TIMEOUT	600	Maximum timeout (seconds)
OPENCODE_SERVER_LOG_LEVEL	INFO	Logging level

Architecture

src/services/fast_mcp/opencode_server/
├── __init__.py
├── __main__.py          # Entry point
├── server.py            # MCP server & tool definitions
├── opencode_executor.py # CLI execution wrapper
├── models.py            # Pydantic models
├── settings.py          # Configuration
└── handlers/
    ├── __init__.py
    ├── execution.py     # Run/continue operations
    ├── session.py       # Session management
    └── discovery.py     # Model/status discovery

Development

Running Tests

pytest tests/ -v

Code Formatting

black src/
ruff check src/

Roadmap

Planned features for v2.0:

• [ ] opencode_import_session - Import sessions from JSON/URL
• [ ] opencode_list_sessions - List all sessions with filtering
• [ ] opencode_get_stats - Usage statistics and cost tracking
• [ ] opencode_list_agents - List available agents
• [ ] opencode_github_run - GitHub Actions integration (async)
• [ ] opencode_pr_checkout - PR workflow support

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

License

MIT License - see LICENSE for details.

Related Projects

• OpenCode - The AI coding agent this server integrates with
• Model Context Protocol - The protocol specification
• MCP SDK - Python SDK for MCP

Acknowledgments

• SST Team for creating OpenCode
• Anthropic for the MCP specification