Olist MCP

Servidor Model Context Protocol (MCP) open source e auto-hospedável para a API V2 do Olist ERP (Tiny). Funciona por stdio, portanto pode ser usado pelo Codex, Claude Desktop e qualquer cliente/harness compatível com MCP.

A API V2 permanece funcional, mas a Olist informa que ela não receberá novos recursos. Este projeto usa a documentação pública V2, pois não há especificação OpenAPI publicada.

Recursos

Uma ferramenta MCP individual para cada um dos 92 endpoints REST V2 que a documentação pública apresenta com URL REST, como olist_produto_obter, olist_nota_fiscal_pesquisa e olist_conta_receber_baixar;
Schemas de entrada e descrições dos parâmetros extraídos da página oficial de cada serviço;
Proteção contra escrita: ferramentas que incluem, alteram, atualizam, baixam, lançam, estornam, emitem, excluem, cancelam, geram, enviam ou concluem exigem confirmar: true.

As chamadas são feitas por POST com application/x-www-form-urlencoded, incluindo token e formato=JSON, exatamente no formato apresentado pela documentação V2.

Pré-requisitos

Node.js 20 ou superior;
um token da API Olist/Tiny, gerado no ERP. Não envie esse token em conversas nem o versiona em arquivos.

Instalação e execução local

git clone <URL_DESTE_REPOSITORIO> olist-mcp
cd olist-mcp
npm install
npm run build
export OLIST_API_TOKEN='seu-token'
npm start

O processo não abre porta HTTP: o cliente MCP inicia o executável e conversa por entrada/saída padrão. Para desenvolvimento, use npm run dev.

Para instalar globalmente após publicar o pacote no npm, o comando será npm install -g olist-mcp; até lá, prefira apontar o harness para o dist/index.js deste clone.

Configuração no Codex

Depois do npm run build, adicione uma entrada ao arquivo de configuração MCP do Codex (substitua o caminho absoluto e o token):

[mcp_servers.olist]
command = "node"
args = ["/caminho/absoluto/olist-mcp/dist/index.js"]

[mcp_servers.olist.env]
OLIST_API_TOKEN = "seu-token"

Reinicie a sessão do Codex. Nunca use npm start como command: MCP precisa iniciar o processo diretamente, sem um shell intermediário.

Configuração no Claude Desktop

No arquivo de configuração do Claude Desktop, inclua (ou mescle) o bloco abaixo:

{
  "mcpServers": {
    "olist": {
      "command": "node",
      "args": ["/caminho/absoluto/olist-mcp/dist/index.js"],
      "env": {
        "OLIST_API_TOKEN": "seu-token"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar. Em Windows, use barras duplas no caminho JSON, por exemplo C:\\Projetos\\olist-mcp\\dist\\index.js.

Qualquer outro harness MCP

Configure um transporte stdio com:

command: node
args: ["/caminho/absoluto/olist-mcp/dist/index.js"]
env: { OLIST_API_TOKEN: "seu-token" }

Ferramentas, schemas e atualização do catálogo

Não há uma ferramenta genérica: cada endpoint REST documentado vira uma ferramenta MCP própria. Os campos obrigatórios, tipos (string, int, decimal e objeto JSON) e descrições vêm da tabela “Parâmetros do serviço” de sua página oficial. token e formato não aparecem no schema porque o servidor os inclui automaticamente.

Para atualizar o catálogo quando a Olist modificar a documentação:

npm run generate:catalog
npm run check && npm test && npm run build

O gerador salva o resultado versionado em src/generated/catalog.ts; portanto a instalação normal não precisa acessar a internet. Das 127 páginas api2-* referenciadas no índice atual, 92 expõem uma URL REST e geram ferramentas. As demais são páginas explicativas (limites, token, webhooks, fluxos ou tabelas auxiliares), não endpoints invocáveis.

Operações de escrita requerem confirmar: true, mesmo que o agente já tenha recebido instrução em linguagem natural. Esse é um último guard rail; ele não substitui a revisão dos parâmetros pelo usuário.

Endpoints e documentação

A Olist publica a lista de serviços e páginas individuais em HTML, no padrão https://tiny.com.br/api-docs/api2-*. Como não existe um OpenAPI oficial, este servidor não tenta inventar schemas para todos os endpoints: a ferramenta genérica encaminha os parâmetros documentados e os atalhos cobrem as consultas mais frequentes.

Referências oficiais:

Desenvolvimento

npm test
npm run check
npm run build

Para testes automatizados, defina OLIST_API_BASE_URL para um mock/proxy local, se necessário. Não há telemetria e o token só é usado na chamada à API Olist.

Licença

MIT.