MCP ssOtica

Servidor MCP local em Python para as seis APIs consultivas documentadas do ssOtica. Faz somente requisições GET, autentica com Bearer Token, pagina automaticamente quando a API informa páginas e salva cada consulta em CSV UTF-8, com objetos aninhados em colunas com ponto.

Instalação

Use Python 3.10 ou posterior.

cd /ssotica-mcp
python3.12 -m venv .venv-mcp
source .venv-mcp/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edite .env e informe SSOTICA_TOKEN (Bearer Token enviado pelo ssOtica). Os seis endpoints já vêm configurados.

Related MCP server: Acme Operations Assistant

Tools disponíveis

Todas recebem empresa. O servidor aceita CNPJ sem pontuação ou Código da Licença e resolve automaticamente via data/empresas.csv. Se um CNPJ tiver várias licenças, informe também licenca com o código da unidade desejada.

Argumentos opcionais:

• Período: data_inicio, data_fim (YYYY-MM-DD; padrão: mês atual até hoje)

• Desambiguação: licenca (obrigatório quando o CNPJ possui várias licenças em data/empresas.csv)

• Produtos: referencia, produto_id, page, per_page (máx. 100)

• Contas a pagar: tipo_periodo (vencimento, cancelamento, pagamento, lançamento, emissao), conta_id, documento, emissao, page, per_page

• Contas a receber: tipo_periodo (vencimento, cancelamento, pagamento, lançamento, renegociacao), conta_id, documento, renegociacao, page, per_page

Com conta_id, os demais filtros de período são ignorados (conforme documentação da API).

Exemplos:

consultar-vendas-ativas empresa=42547637000142 licenca=RODO-UYEN data_inicio=2026-07-01 data_fim=2026-07-10
consultar-produtos-estoque empresa=42547637000142 licenca=RODO-UYEN referencia=ABC-123
consultar-contas-pagar empresa=RODO-UYEN tipo_periodo=pagamento data_inicio=2025-08-01 data_fim=2025-08-31

Arquivos gerados

CSVs em data/, organizados por tipo: vendas/, ordens_servico/, lancamentos_financeiros/, produtos_estoque/, contas_pagar/ e contas_receber/.

Solução de problemas

• 401 / 403: token inválido, expirado ou sem permissão.

• 404: confirme se a conta possui acesso à API consultiva contratada.

• Período inválido: vendas, O.S. e extrato aceitam no máximo 30 dias por consulta.

• CNPJ com várias licenças: informe licenca com o Código da Licença da unidade (ex.: RODO-UYEN, XLNH-PLI).

• Sem resultados: é gerado um CSV com cabeçalho; revise identificador, período e filtros.