Saltar para o conteúdo principal
O servidor MCP do Orkestral é um pacote independente (@orkestral/mcp) que expõe seu workspace do Orkestral via Model Context Protocol (MCP). Você o registra em um cliente MCP como o Claude Code, e o cliente ganha ferramentas para ler e editar sua base de conhecimento, além de ler suas issues, fontes e a visão geral do workspace. O servidor conversa com o mesmo banco de dados local que o app desktop usa (~/.orkestral/instances/default/db/orkestral.db, em modo WAL). Você não precisa do app aberto: ambos os processos compartilham o arquivo SQLite com segurança graças ao WAL e a um busy timeout. O pacote também traz uma CLI orkestral e uma API REST local opcional que reutilizam o mesmo core e as mesmas ferramentas.

Base de conhecimento

A KB que este servidor lê e edita.

Workspaces

Cada sessão MCP aponta para um workspace.

​
O que é

O servidor é uma fina camada de transporte sobre o core compartilhado do Orkestral. Ele empacota o schema, os repositórios e o registro único de ferramentas da KB (kb-mcp-tools) do app via esbuild, então há uma única fonte da verdade: apenas o transporte difere entre o servidor embarcado do app desktop e este processo independente.
O pacote existe separadamente porque o better-sqlite3 do app desktop é compilado para a ABI do Electron. Um processo Node simples (o que claude mcp add -- npx ... executa) não consegue carregá-lo. Por isso este pacote mantém seu próprio node_modules com better-sqlite3 compilado para a ABI do Node.

​
Requisitos

  • Node.js 20 ou posterior (engines.node é >=20).
  • Um banco de dados Orkestral existente em ~/.orkestral/instances/default/db/orkestral.db, criado ao executar o app desktop pelo menos uma vez e criar um workspace.
  • Pelo menos um workspace nesse banco de dados. Use orkestral workspaces (ou a ferramenta list_workspaces) para encontrar os ids dos workspaces.
  • Um cliente MCP que fale stdio, como o Claude Code.
O servidor independente reutiliza módulos nativos que precisam corresponder à sua plataforma local e à ABI do Node. Se você instalar a partir de um clone, execute npm install para que o better-sqlite3 seja compilado para a sua versão do Node antes de fazer o build.

​
Configuração

1

Faça o build do pacote (instalação local)

A partir de um clone do pacote:
cd orkestral-mcp
npm install     # compiles better-sqlite3 for the Node ABI
npm run build   # esbuild → dist/index.js (MCP) + dist/cli.js (CLI)
2

Encontre o id do seu workspace

orkestral workspaces
Isso lista cada workspace como id e name. Copie o id que você quer que o servidor aponte.
3

Registre o servidor no Claude Code

Aponte o Claude Code para o entry compilado, passando o id do workspace:
# local (after build):
claude mcp add orkestral -- node /path/to/orkestral-mcp/dist/index.js --workspace <id>

# via npx (after the package is published to NPM):
claude mcp add orkestral -- npx -y -p @orkestral/mcp orkestral mcp --workspace <id>
Sem --workspace, o servidor resolve o alvo por conta própria se houver exatamente um workspace no banco de dados.
4

Confirme que as ferramentas estão disponíveis

No seu cliente MCP, liste as ferramentas disponíveis. Você deve ver list_workspaces, as ferramentas kb_* e as ferramentas de leitura do workspace descritas abaixo.

​
Opções de configuração

Você configura o servidor por meio de flags de comando ou variáveis de ambiente passadas no momento do registro.
​
--workspace, -w <id>
string
Workspace alvo, por id ou name (a correspondência por nome não diferencia maiúsculas de minúsculas). Se omitido, o servidor usa o único workspace quando há exatamente um. Com múltiplos workspaces e sem a flag, as chamadas falham até você registrar novamente com um workspace.
​
ORKESTRAL_WORKSPACE
env var
Alternativa a --workspace. O servidor lê esta variável de ambiente quando nenhuma flag --workspace está presente.
​
--status <s>
string
Filtro exclusivo da CLI para orkestral issues. Um de backlog, todo, in_progress, in_review, blocked, done, cancelled.
​
--limit <n>
number
Limite de resultados exclusivo da CLI para comandos de listagem (busca na KB e issues).
​
--port <n>
number
padrão:"3100"
Porta para orkestral serve (a API REST local). O servidor faz bind apenas em 127.0.0.1.
O caminho do banco de dados é fixo: o servidor sempre abre ~/.orkestral/instances/default/db/orkestral.db. Não há flag para apontá-lo para outro lugar.

​
Transporte

O servidor MCP fala JSON-RPC 2.0, delimitado por nova linha, via stdio. Ele implementa initialize, notifications/initialized, ping, tools/list e tools/call. A versão de protocolo reportada por padrão é 2025-06-18, e ele ecoa o protocolVersion do cliente quando um é fornecido.
O stdout é exclusivamente o canal do protocolo. Todos os logs internos (incluindo mensagens de abertura do banco de dados) vão para o stderr. Não escreva mais nada no stdout, ou você corromperá o stream. O servidor já redireciona console.log para o stderr para proteger o canal.
Os resultados das ferramentas voltam como um único bloco de conteúdo text contendo JSON formatado. Erros de ferramentas são retornados no resultado com isError: true, em vez de como erros JSON-RPC.

​
Ferramentas disponíveis

O servidor expõe 20 ferramentas. As ferramentas da base de conhecimento vêm do registro compartilhado; o restante são ferramentas independentes de descoberta e leitura.
FerramentaFinalidade
kb_searchBusca BM25 em toda a base de conhecimento.
kb_get_pageLê uma página por id ou slug.
kb_get_page_treeA árvore de páginas do workspace.
kb_get_backlinksPáginas que apontam para uma dada página.
Issues e fontes são somente leitura no servidor independente. Criar uma issue dispara a execução de agentes, que é responsabilidade do app desktop, então o servidor não expõe ferramentas de escrita para isso.

​
CLI

A CLI orkestral empacotada acessa o mesmo banco de dados compartilhado diretamente. É útil para verificações rápidas e para iniciar o servidor.
ComandoDescrição
orkestral workspacesLista workspaces (id + name).
orkestral kb search <terms...>Busca BM25 na KB.
orkestral kb treeÁrvore de páginas.
orkestral kb get <id|slug>Lê uma página.
orkestral issues [--status <s>]Lista issues.
orkestral issue <key>Lê uma issue por número.
orkestral sourcesLista repositórios e pastas.
orkestral infoVisão geral do workspace mais metas.
orkestral mcpExecuta o servidor MCP stdio.
orkestral serve [--port 3100]Executa a API REST local.
Assim como o servidor, a CLI escreve os resultados no stdout e os logs no stderr, então você pode redirecionar a saída com segurança.

​
API REST

orkestral serve expõe o mesmo core e as mesmas ferramentas via HTTP em 127.0.0.1 (apenas localhost). Escolha o workspace por requisição com ?workspace=, o cabeçalho x-orkestral-workspace, ou recorra ao padrão. 
GET    /workspaces
GET    /kb/search?q=&limit=     GET  /kb/tree           GET /kb/page/:idOrSlug
POST   /kb/page                 PATCH /kb/page/:idOrSlug DELETE /kb/page/:idOrSlug
GET    /issues?status=&limit=   GET  /issues/:key
GET    /sources                 GET  /info
GET / e GET /health retornam um pequeno objeto de status. Rotas desconhecidas retornam 404; erros de ferramentas retornam 400 com uma mensagem error.

​
Capacidades e limites

  • Banco de dados compartilhado: leituras e escritas chegam no mesmo arquivo SQLite que o app desktop. As mudanças são visíveis nos dois processos.
  • Autocontido: o pacote publicado empacota o core do app, com better-sqlite3 e drizzle-orm como dependências de runtime, então npx -y @orkestral/mcp funciona após a publicação.
  • Um workspace por processo: cada instância de servidor registrada aponta para um único workspace resolvido (exceto list_workspaces, que funciona sem um).
  • Sem escrita de issues ou fontes: esses fluxos pertencem ao app desktop.
  • Sem acesso remoto: a API REST faz bind apenas em localhost; não há listener de rede para o transporte MCP (ele é stdio).

​
Solução de problemas

O servidor não conseguiu resolver um único workspace. Registre novamente com --workspace <id> (ou defina ORKESTRAL_WORKSPACE). Execute orkestral workspaces ou chame list_workspaces para obter os ids. Isso acontece quando o banco de dados tem zero ou múltiplos workspaces e nenhuma flag foi fornecida.
A referência não correspondeu a nenhum id de workspace e nenhum nome correspondeu (sem diferenciar maiúsculas de minúsculas). O erro lista os workspaces disponíveis como name (id). Copie um id exato de orkestral workspaces.
O módulo nativo precisa corresponder à sua ABI do Node. Execute npm install e depois npm run build a partir do pacote com a mesma versão do Node com a qual você inicia o servidor. Confirme que o Node é 20 ou posterior.
O servidor abre ~/.orkestral/instances/default/db/orkestral.db. Abra o app desktop uma vez e crie um workspace para que o banco de dados e o schema existam.
Algo escreveu no stdout fora do canal JSON-RPC. Certifique-se de iniciar o servidor pelo entry dist/index.js (ou orkestral mcp) e não redirecione saída extra para ele. Logs internos pertencem ao stderr.
Passe ?workspace=<id> ou o cabeçalho x-orkestral-workspace por requisição. Sem nenhum dos dois, o servidor usa o padrão resolvido na inicialização do serve.
Inicie o servidor com node dist/index.js --workspace <id> diretamente em um terminal para observar a linha de inicialização no stderr. Ela reporta o workspace resolvido (ou o motivo pelo qual não conseguiu resolver um) antes de qualquer cliente se conectar.