opencode-mcp

opencode-mcp

Um servidor MCP (Model Context Protocol) que permite que qualquer host MCP — Claude Code, Codex, Cursor, etc. — controle uma instância do OpenCode e delegue trabalho aos seus subagentes — para que modelos orquestradores como Opus ou Fable possam repassar tarefas aos outros modelos que o OpenCode expõe.

Instalação rápida

Requer Node.js 18+ e OpenCode instalado e configurado (opencode deve estar no seu PATH, com pelo menos um provedor/modelo configurado) — este servidor inicia e controla instâncias do OpenCode.

Para Claude Code:

claude mcp add opencode -- npx -y mcp-server-opencode

Para Codex:

codex mcp add opencode -- npx -y mcp-server-opencode

Consulte Instalação para configuração manual e opções a partir do código-fonte.

Ferramentas

Ferramenta	Descrição
opencode_start_server	Inicia (ou anexa a) uma instância do servidor OpenCode
opencode_stop_server	Para uma instância do servidor OpenCode em execução
opencode_list_agents	Lista agentes/modelos disponíveis em uma instância do servidor
opencode_start_task	Delega uma tarefa a um agente iniciando uma nova sessão e prompt (substituição opcional de agent / model)
opencode_continue_task	Envia um prompt de acompanhamento à sessão de uma tarefa existente para interação iterativa com o subagente
opencode_cancel_task	Aborta uma tarefa delegada em execução cancelando sua sessão
opencode_get_task_status	Consulta o status de uma tarefa delegada (pending / running / completed / failed); include_progress opcional adiciona um trecho de saída parcial e a ferramenta atualmente em execução enquanto ela ainda está em execução
opencode_get_task_result	Busca o resultado final de uma tarefa concluída
opencode_wait_for_task	Faz long-poll de uma ou mais tarefas delegadas até que terminem (mode: "all" ou "any") ou o tempo limite expire; include_progress opcional enriquece quaisquer tarefas ainda não concluídas no resultado final com um trecho de saída parcial e a ferramenta atualmente em execução

Prompt	Descrição
delegate_task	Guia o host na delegação de uma ou mais tarefas aos agentes do OpenCode (fluxo de trabalho iniciar/aguardar/resultado), incluindo um guia de seleção de modelos que mapeia cada nível de modelo do OpenCode à dificuldade da tarefa que ele deve lidar

Como funciona

A delegação de tarefas é assíncrona: iniciar uma tarefa retorna imediatamente com um task_id em vez de bloquear até que o subagente termine. Isso permite que o Claude Code dispare múltiplas chamadas opencode_start_task em paralelo — cada uma abre um Session isolado do OpenCode — sem atingir os timeouts do cliente MCP em trabalhos de longa duração. Status e resultados são buscados separadamente via polling.

Instalação

Pré-requisitos

• Node.js 18+
• OpenCode instalado e configurado (opencode deve estar no seu PATH, com pelo menos um provedor/modelo configurado) — este servidor inicia e controla instâncias do OpenCode.

Opção 1 — npm (recomendado)

O pacote é publicado como mcp-server-opencode. Não é necessário clonar ou compilar — aponte seu host MCP para npx:

Para Claude Code, um único comando resolve:

claude mcp add opencode -- npx -y mcp-server-opencode

Ou manualmente

{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "mcp-server-opencode"]
    }
  }
}

Para Codex, adicione o servidor ao ~/.codex/config.toml:

[mcp_servers.opencode]
command = "npx"
args = ["-y", "mcp-server-opencode"]

Ou instale globalmente e use o binário diretamente:

npm install -g mcp-server-opencode

{
  "mcpServers": {
    "opencode": {
      "command": "opencode-mcp"
    }
  }
}

Opção 2 — a partir do código-fonte

git clone https://github.com/alejandro-technology/opencode-mcp.git
cd opencode-mcp
pnpm install
pnpm build

Em seguida, aponte seu host MCP para o entrypoint compilado:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/build/src/index.js"]
    }
  }
}

Reinicie seu host MCP após editar a configuração; as ferramentas opencode_* devem aparecer na lista de ferramentas.

Configuração

MCP_TOOL_TIMEOUT

opencode_wait_for_task aceita uma entrada timeout_ms, mas ela é limitada a um máximo no lado do servidor para que uma única chamada não bloqueie a conexão MCP indefinidamente. Esse máximo é padronizado em 300000 ms (5 minutos) e é configurável via MCP_TOOL_TIMEOUT.

MCP_TOOL_TIMEOUT pode ser definido de duas maneiras:

• Variável de ambiente — defina-a na configuração do servidor MCP:

  {
    "mcpServers": {
      "opencode": {
        "command": "node",
        "args": ["/path/to/opencode-mcp/build/src/index.js"],
        "env": { "MCP_TOOL_TIMEOUT": "1200000" }
      }
    }
  }
  

• Argumento de CLI — passe MCP_TOOL_TIMEOUT=<ms> como um argumento extra ao processo do servidor:

  {
    "mcpServers": {
      "opencode": {
        "command": "node",
        "args": [
          "/path/to/opencode-mcp/build/src/index.js",
          "MCP_TOOL_TIMEOUT=1200000"
        ]
      }
    }
  }
  

Se ambos estiverem presentes, a variável de ambiente tem precedência sobre o argumento de CLI. Valores inválidos ou não numéricos voltam ao padrão de 300000 ms.

Desenvolvimento

Estrutura do projeto

src/
├── index.ts                   # MCP server entrypoint (stdio transport, shutdown handlers)
└── modules/
    ├── tools/                 # One file per MCP tool, registered in index.ts
    ├── prompts/               # One file per MCP prompt, registered in index.ts
    └── shared/                # Cross-tool infrastructure
        ├── server-registry.ts   # Tracks running OpenCode servers; killAllServers() on shutdown
        ├── task-registry.ts     # Maps task_id → OpenCode server + session
        ├── opencode-client.ts   # Builds SDK clients from the registries
        ├── config.ts            # MCP_TOOL_TIMEOUT resolution (env var / CLI arg)
        └── mcp-result.ts        # jsonResult / jsonError MCP output helpers

Cada módulo acompanha uma suíte *.test.ts Vitest sob a árvore tests/ paralela que espelha src/.

Primeiros passos

pnpm install
pnpm dev     # runs the server through the MCP Inspector (tsx, no build needed)

Outros scripts:

pnpm test           # vitest run
pnpm test:coverage  # vitest run --coverage
pnpm lint           # biome check
pnpm lint:write     # biome check --write
pnpm build          # clean tsc build to ./build (also the typecheck)