Olist Mcp Server

Olist ERP MCP Server

Servidor MCP para a API Olist ERP (Tiny ERP) v3 com 168 tools geradas automaticamente do Swagger da API.

Compativel com qualquer cliente MCP — Claude Code, Claude Desktop, n8n, Cursor, etc.

O que faz

Conecta qualquer agente de IA ao Olist ERP. As 168 tools cobrem todas as operacoes da API:

| Categoria | Tools | Operacoes | |---|---|---| | Produtos | 24 | CRUD, estoque, precos, kits, anexos | | Pedidos de Venda | 14 | CRUD, notas, etiquetas, rastreio | | Contatos | 14 | CRUD, tipos, busca | | Contas a Pagar | 14 | CRUD, baixa, estorno | | Contas a Receber | 14 | CRUD, baixa, estorno, boletos | | Notas Fiscais (NFe/NFCe) | 18 | Emissao, consulta, XML, cancelamento | | PDV | 10 | Vendas, sessoes, caixa | | CRM | 8 | Oportunidades, funil | | Contratos | 6 | CRUD, parcelas | | Ordem de Servico | 6 | CRUD | | Expedicao | 8 | Volumes, objetos, etiquetas | | Catalogo | 16 | Categorias, marcas, depositos, vendedores | | Configuracoes | 16 | Empresa, formas pgto, parcelas |

Quick Start

1. Configure o .env

cp .env.example .env

Preencha com suas credenciais Olist:

MCP_SERVER_NAME=olist-erp
SWAGGER_URL=https://erp.tiny.com.br/public-api/v3/swagger/swagger.json

OAUTH_CLIENT_ID=seu-client-id
OAUTH_CLIENT_SECRET=seu-client-secret
OAUTH_AUTH_URL=https://accounts.tiny.com.br/realms/tiny/protocol/openid-connect/auth
OAUTH_TOKEN_URL=https://accounts.tiny.com.br/realms/tiny/protocol/openid-connect/token
OAUTH_REDIRECT_URI=http://localhost:47321/auth/callback
OAUTH_SCOPE=openid

> Para obter client_id e client_secret, crie uma aplicacao no painel de integracoes da sua conta Olist ERP (Tiny).

2. Suba o server

# Docker (recomendado)
docker compose up -d

# Ou local
pip install -r requirements.txt
python -m src.server

3. Autentique com a Olist

Abra http://localhost:47321/auth no browser e autorize a aplicacao na conta Olist.

4. Crie um token de acesso

curl -X POST http://localhost:47321/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"name": "meu-token"}'

Guarde o token retornado — sera necessario para acessar o endpoint /mcp.

5. Conecte seu agente

Configure o MCP client apontando para http://localhost:47321/mcp com o header Authorization: Bearer SEU_TOKEN.

Configuracao

| Variavel | Default | Descricao | |---|---|---| | MCP Server | | | | MCP_SERVER_NAME | swagger-mcp | Nome do server MCP | | MCP_SERVER_INSTRUCTIONS | (auto) | Instrucoes do server para o LLM | | MCP_TRANSPORT | streamable-http | Transporte: streamable-http, sse ou stdio | | MCP_HOST | 0.0.0.0 | Host do servidor | | MCP_PORT | 47321 | Porta do servidor | | Swagger | | | | SWAGGER_URL | — | URL do swagger spec (fetched no startup, cached localmente) | | API | | | | API_BASE_URL | (auto do spec) | Base URL da API (auto-detectado do servers[0].url do swagger) | | OAuth2 | | | | OAUTH_CLIENT_ID | — | Client ID (obrigatorio) | | OAUTH_CLIENT_SECRET | — | Client Secret (obrigatorio) | | OAUTH_AUTH_URL | — | URL de autorizacao OAuth | | OAUTH_TOKEN_URL | — | URL de troca de tokens | | OAUTH_REDIRECT_URI | http://localhost:47321/auth/callback | Redirect URI | | OAUTH_SCOPE | openid | Scopes OAuth | | OAUTH_TOKEN_FILE | data/.oauth_tokens.json | Caminho para persistir tokens OAuth | | API Token | | | | MCP_TOKEN_FILE | data/.mcp_tokens.json | Caminho para persistir tokens de acesso |

Autenticacao OAuth2

O servidor embute o fluxo OAuth2 completo com a Olist via rotas HTTP.

Fluxo

1. Suba o servidor — funciona mesmo sem tokens
2. Abra /auth no browser — redireciona para login da Olist
3. Autorize a aplicacao — redireciona de volta para /auth/callback
4. Tokens salvos — troca o code por tokens e salva em data/.oauth_tokens.json
5. Pronto — todas as 168 tools funcionam

Tokens sao renovados automaticamente via refresh token. Se expirar, abra /auth novamente.

Seguranca — Token de Acesso

O endpoint /mcp e protegido por Bearer token. Ao criar o primeiro token, a autenticacao e ativada automaticamente — qualquer request sem token valido recebe 401 Unauthorized.

Rotas publicas (sem token): /auth, /auth/callback, /auth/status, /health, /info, /api/tokens.

Criar token

curl -X POST http://localhost:47321/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"name": "meu-token", "description": "Token para meus scripts"}'

Resposta:

{
  "token": "dKx8vZ-pQ_H2mN4r8tL9...",
  "name": "meu-token",
  "message": "Save this token securely. You won't be able to see it again."
}

Usar o token

curl -X POST http://localhost:47321/mcp \
  -H 'Authorization: Bearer dKx8vZ-pQ_H2mN4r8tL9...' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

Listar tokens

curl http://localhost:47321/api/tokens

Revogar token

curl -X DELETE http://localhost:47321/api/tokens/dummy \
  -H 'Content-Type: application/json' \
  -d '{"token": "dKx8vZ-pQ_H2mN4r8tL9..."}'

> Tokens sao salvos com hash SHA-256. Se perder o token, crie um novo.

Rotas HTTP

| Rota | Descricao | |---|---| | GET /auth | Redireciona para login OAuth da Olist | | GET /auth/callback | Recebe o code e troca por tokens | | GET /auth/status | Retorna {"authenticated": true/false} | | GET /api/tokens | Lista tokens ativos | | POST /api/tokens | Cria novo token | | DELETE /api/tokens/{hash} | Revoga token | | GET /health | Health check (200 healthy / 503 degraded) | | GET /info | Metadata: nome, transport, tools, swagger_url | | POST /mcp | Endpoint MCP — requer Bearer token |

Integracao

Claude Desktop

1. Configure o MCP server em claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "olist-erp": {
      "url": "http://localhost:47321/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_AQUI"
      }
    }
  }
}

2. Adicione o Agent Prompt — copie o conteudo de [agents/olist-erp.md](agents/olist-erp.md) como Project Instructions no Claude Desktop.

Isso ensina o Claude as quirks da API Olist (validacao de EAN, workflows de NF, regras do ERP brasileiro). Sem o agent prompt, o Claude vai errar frequentemente.

Claude Code

{
  "mcpServers": {
    "olist-erp": {
      "url": "http://localhost:47321/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_AQUI"
      }
    }
  }
}

n8n

1. Suba o container com docker compose up -d
2. Autentique via http://localhost:47321/auth
3. Crie um token: curl -X POST http://localhost:47321/api/tokens -H 'Content-Type: application/json' -d '{"name":"n8n"}'
4. No n8n, adicione um MCP Client node apontando para http://host.docker.internal:47321/mcp com header Authorization: Bearer SEU_TOKEN

stdio (sem Docker)

{
  "mcpServers": {
    "olist-erp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/caminho/para/olist-mcp-server"
    }
  }
}

Docker

docker-compose.yml

services:
  olist-mcp:
    build: .
    ports:
      - "47321:47321"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Imagem do GHCR

docker pull ghcr.io/opastorello/olist-mcp-server:1.0.0

Health check

curl http://localhost:47321/health
# {"status":"healthy","server":"olist-erp","tools":168,"authenticated":true,"transport":"streamable-http"}

Arquitetura

src/
├── server.py           # Entry point - FastMCP + rotas OAuth/health + auth middleware
├── api_client.py       # Cliente HTTP async generico
├── tools_generator.py  # Gera tools dinamicamente do swagger + auto-fetch
├── oauth.py            # OAuth2 token manager (exchange, refresh, persistencia)
├── token_auth.py       # API token manager (SHA-256 hash, CRUD, validacao)
├── __main__.py         # python -m src
└── __init__.py

agents/
└── olist-erp.md        # Agent prompt para Claude Desktop (168 tools documentadas)

O swagger e buscado da SWAGGER_URL no startup e cacheado localmente. Se a Olist adicionar endpoints novos, basta reiniciar o server — novas tools aparecem automaticamente.

Pre-requisitos

• Python 3.12+
• Docker (opcional, recomendado)
• Credenciais OAuth2 da Olist (crie no painel de integracoes da sua conta Olist ERP)

Licenca

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: opastorello
• Source: opastorello/olist-mcp-server
• License: MIT
• Homepage: https://api-docs.erp.olist.com

Install and usage instructions live in the source repository linked above.