Servidor MCP da FiscalAPI. Deixa um agente de IA (Claude, Cursor, VS Code, ChatGPT) consultar Inscrição Estadual nos 27 estados, CNPJ, Simples Nacional, NFS-e por chave, CND estadual, CNDT, CND Federal, CRF/FGTS e baixar uma cópia para leitura do XML de NF-e pela chave de acesso (sem a assinatura digital), usando a sua conta da FiscalAPI.
Endereço: https://mcp.fiscalapi.com.br/mcp (Streamable HTTP)
Duas ferramentas funcionam sem chave e não cobram nada: validar_inscricao_estadual e cobertura. As outras usam a sua chave da FiscalAPI e cobram do saldo da conta, como a API REST.
Para consultar dados reais: crie a chave em app.fiscalapi.com.br e tenha plano ou créditos extras (planos a partir de R$ 50 por mês).
A chave vai no header X-API-Key (também aceita Authorization: Bearer <chave>). Troque fapi_sua_chave pela sua.
claude mcp add --transport http fiscalapi https://mcp.fiscalapi.com.br/mcp --header "X-API-Key: fapi_sua_chave"Para não deixar a chave no histórico do terminal, guarde-a numa variável de ambiente e use --header "X-API-Key: $FISCALAPI_API_KEY".
.cursor/mcp.json (no projeto) ou ~/.cursor/mcp.json (global):
{
"mcpServers": {
"fiscalapi": {
"url": "https://mcp.fiscalapi.com.br/mcp",
"headers": {
"X-API-Key": "${env:FISCALAPI_API_KEY}"
}
}
}
}.vscode/mcp.json. O VS Code pede a chave na primeira vez e guarda de forma segura:
{
"inputs": [
{
"type": "promptString",
"id": "fiscalapi-chave",
"description": "Chave da FiscalAPI",
"password": true
}
],
"servers": {
"fiscalapi": {
"type": "http",
"url": "https://mcp.fiscalapi.com.br/mcp",
"headers": {
"X-API-Key": "${input:fiscalapi-chave}"
}
}
}
}Crie um conector com a URL https://mcp.fiscalapi.com.br/mcp, sem autenticação. Os conectores do ChatGPT aceitam só OAuth ou nenhuma autenticação, não uma chave de API em header, então por lá funcionam só as ferramentas sem chave (validar_inscricao_estadual e cobertura). Para as consultas pagas, use um cliente que envia o header, como os de cima.
O saldo da conta é em créditos (1 crédito = R$ 1), e cada consulta desconta o preço dela. Preço de 1 consulta por plano, com os créditos do plano (com créditos extras entre parênteses): Starter R$ 0,10 (R$ 0,12); Pro R$ 0,065 (R$ 0,085); Enterprise R$ 0,025 (R$ 0,035). Como funcionam os créditos: https://fiscalapi.com.br/creditos/ . Consulta que termina em erro não é cobrada; resposta sem inscrição encontrada, sem_certidao ou nao_contribuinte conta como consulta.
| Ferramenta | O que faz | Custo |
|---|---|---|
validar_inscricao_estadual |
Confere formato e dígito verificador da IE na UF. Não diz se a IE existe ou está ativa. | Sem chave, sem custo |
cobertura |
O que a FiscalAPI consulta, por produto e UF, e os limites da API. | Sem chave, sem custo |
consultar_ie |
Inscrição Estadual numa UF, por CPF, CNPJ ou IE (por CPF, todos os estados menos SP). | 1 consulta |
consultar_ie_todos_estados |
Inscrições nos 27 estados numa chamada, por CPF, CNPJ ou IE. | 1 consulta |
consultar_cnpj |
Cadastro público do CNPJ na Receita Federal, com Simples e MEI. ao_vivo=true consulta na hora. |
1 consulta; ao vivo, R$ 0,30 (Starter), R$ 0,195 (Pro) ou R$ 0,075 (Enterprise) |
consultar_simples_nacional |
Situação do CNPJ no Simples Nacional, SIMEI e regimes IBS/CBS. | 1 consulta |
consultar_nfse |
NFS-e do padrão nacional pela chave de 50 dígitos, sem certificado. O PDF do DANFSe fica na API REST. | R$ 0,30 (Starter), R$ 0,195 (Pro) ou R$ 0,05 (Enterprise) por nota; só a nota entregue |
consultar_cnd_estadual |
CND estadual (ICMS) de CPF ou CNPJ na UF. | 1 consulta |
consultar_cndt |
Certidão Negativa de Débitos Trabalhistas. | 1 consulta |
consultar_cnd_federal |
Certidão de tributos federais e Dívida Ativa da União (CPF exige data_nascimento). |
1 consulta |
consultar_crf_fgts |
Certificado de Regularidade do FGTS. | 1 consulta |
baixar_xml_nfe_sem_certificado |
Cópia para leitura do XML de uma NF-e (modelo 55) pela chave de acesso, sem a assinatura digital. | R$ 0,30 (Starter), R$ 0,195 (Pro) ou R$ 0,05 (Enterprise) por chave |
saldo |
Saldo em créditos (do plano, extras, guardados e disponível) e quanto ele ainda rende, em consultas e em notas. | Não consome consulta |
Pelo MCP toda consulta pede plano ou créditos extras, a partir de R$ 50 por mês. As 10 consultas grátis do mês são só no painel (app.fiscalapi.com.br). O XML de NF-e sem certificado cobra também a chave cuja nota não foi encontrada (menos a mesma chave repetida logo depois).
O XML de NF-e e de CT-e com certificado e o DIFAL de saída não existem no MCP: o certificado e a senha passariam pelo contexto do modelo. Use a API REST ou o painel.
O PDF das certidões não volta pelo MCP (é grande demais para o modelo). Na API REST ele vem no campo pdf_base64; repetir a consulta lá cobra de novo.
- Toda ferramenta que cobra tem o parâmetro
confirmo_custo. Semconfirmo_custo=true, ela só explica o custo e não consulta nada. O agente deve mostrar o custo e esperar o seu OK. - Este servidor aceita até 30 consultas pagas por hora por chave (chave recusada pela API não conta). Para volume, use a API REST direto.
- Valem também os limites da sua conta: por minuto, Starter 20, Pro 60 e Enterprise 120 consultas (conta sem plano: 5); XML de NF-e sem certificado, 2 consultas simultâneas.
- A chave só é repassada à API da FiscalAPI (
https://api.fiscalapi.com.br) no headerX-API-Key, a cada chamada. O servidor não tem banco de dados, não registra headers e não guarda a chave: para contar o teto por hora, mantém em memória só um hash (SHA-256) dela, descartado depois que a janela de 1 hora passa (ou quando a chave é recusada pela API). - O servidor só fala com
api.fiscalapi.com.br; os caminhos são fixos no código e o que você informa vai como parâmetro. - O código está aqui, com licença MIT.
Requer uv e Python 3.12.
uv sync
uv run ruff check .
uv run pytest -q
uv run python -m fiscalapi_mcp # sobe em http://localhost:8000/mcp (porta em PORT)Os testes não chamam a API de verdade: as respostas são simuladas.
MIT. Veja LICENSE.