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 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: omie-mcp

Registrar no Cursor

Em Settings → MCP → Add new MCP server, ou em .cursor/mcp.json:

{
  "mcpServers": {
    "ssotica": {
      "command": "~/mcp/.venv-mcp/bin/python",
      "args": ["~/mcp/mcp_server.py"]
    }
  }
}

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 uma API da ssOtica aceitar somente CNPJ e esse CNPJ tiver várias licenças, o servidor consulta o CNPJ normalmente e salva o resultado agregado do conjunto.

Argumentos opcionais:

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

• Desambiguação: licenca (usada nas APIs que aceitam Código da Licença)

• 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 em API somente por CNPJ: a consulta retorna o agregado do CNPJ; a API ssOtica não retorna a licença nos registros para separar as unidades.

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