Skip to main content
Glama
kud

mcp-opencode

by kud
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

TypeScript Node.js npm MIT

MCP server for opencode — query github-copilot models via a persistent opencode server.

Website · Documentation

Features

  • Zero API key — routes prompts through a locally running opencode server, so no provider credentials are needed in your AI client.

  • Multi-model support — any model configured in opencode is available; query GPT-4.1, Claude, Gemini, or any other supported provider.

  • Model filtering — restrict or block models via MCP_OPENCODE_MODEL_ALLOW and MCP_OPENCODE_MODEL_BLOCK environment variables using glob-style patterns.

  • Auto-start — if opencode is not already listening on port 4096, the server spawns it automatically in the background.

  • Session isolation — each query call creates and destroys a dedicated opencode session, preventing state leakage between calls.

  • Works everywhere — compatible with Claude Desktop, Claude Code, Cursor, Windsurf, VSCode, and any MCP-capable client.

Related MCP server: GPT Proxy MCP Server

Install

npm install -g @kud/mcp-opencode

Requires opencode installed with at least one provider configured, and Node.js ≥ 20.

Usage

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-opencode"]
    }
  }
}

To restrict which models are available, pass environment variables:

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "@kud/mcp-opencode"],
      "env": {
        "MCP_OPENCODE_MODEL_ALLOW": "github-copilot/*",
        "MCP_OPENCODE_MODEL_BLOCK": "github-copilot/gpt-4o-mini"
      }
    }
  }
}

Available tools

Tool

Description

query

Send a prompt to an opencode model. Accepts prompt (required) and model (optional, default: github-copilot/gpt-4.1).

list_models

List models available through the running opencode server. Accepts an optional provider filter (e.g. anthropic).

Development

git clone https://github.com/kud/mcp-opencode.git
cd mcp-opencode
npm install
npm run build
npm test

Use the local .mcp.json to connect Claude Code to your dev build, or npm run inspect to open the MCP Inspector against the compiled output.

Script

Purpose

npm run dev

Run from source via tsx

npm run build

Compile TypeScript to dist/

npm test

Run the Vitest test suite

npm run inspect

Open MCP Inspector against the built server

📚 Full documentation → mcp-opencode/docs

Available Tools

2 tools
list_modelsA

List models available for use. Without a provider, returns providers with model counts. Pass a provider name to list its models. Respects allow/block filters (allow: all).

ParametersJSON Schema
NameRequiredDescriptionDefault
providerNoProvider name to filter by (e.g. 'anthropic', 'openai'). Omit to list all providers.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It mentions that the tool respects allow/block filters and has a conditional return based on provider. Missing details on authentication, rate limits, or performance implications, but covers the main behavioral aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The first sentence immediately states the purpose, and the rest adds conditionally relevant detail. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description sufficiently explains the different return structures (providers with counts or models). It is complete for a simple listing tool, though a bit more detail on the return format could help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% but the description adds nuance by explaining the effect of omitting vs providing the parameter (providers with counts vs specific models), going beyond the schema's basic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists models and specifies two behaviors: without provider it returns providers with model counts, with provider it lists its models. This is specific and distinguishes it from sibling 'query'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use each mode (with or without provider) and mentions allow/block filters. However, it does not explicitly contrast with sibling 'query' or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryA

Send a prompt to an opencode model. Defaults to github-copilot/gpt-4.1. Filters — allow: all. Use list_models to see what's available.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoModel to use in provider/model format (default: github-copilot/gpt-4.1)
promptYesThe prompt to send

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions default model and filter behavior ('allow: all'), but does not disclose if the tool is read-only or destructive, rate limits, or auth needs. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with the core action, then defaults and sibling reference.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 2 params and no output schema, description covers purpose, default, and a hint to sibling. Lacks mention of response format or error handling, but sufficient for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, description adds default value for model and specifies format (provider/model). The prompt parameter is clear. Adds meaningful context beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Send a prompt to an opencode model', specifies the resource and action, and provides the default model. Distinguishes from sibling list_models by directing to it for viewing available models.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use list_models to see available models, providing a when-to-use alternative. Does not specify when not to use query, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.1.1
    • First observedlist_models
    • First observedquery
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

The two tools are clearly distinct: 'query' sends a prompt to a model, while 'list_models' retrieves available models. No ambiguity or overlap in their purposes.

Naming Consistency5/5

Both tool names use a consistent verb or verb_noun pattern ('query', 'list_models'). The naming is clear and predictable.

Tool Count3/5

With only 2 tools, the server feels minimal but not unreasonable for a simple query-and-list interface. However, the scope seems narrow for a full model interaction server.

Completeness3/5

The server covers basic querying and model listing, but lacks tools for configuration (e.g., setting filters or providers) or advanced features like streaming or model metadata details. Notable gaps exist.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kud/mcp-opencode'

If you have feedback or need assistance with the MCP directory API, please join our Discord server