FiscalAPI

FiscalAPI MCP

FiscalAPI 的 MCP 服务。可让 AI Agent（Claude、Cursor、VS Code、ChatGPT）查询 27 个州的州级纳税人登记号、CNPJ、州级税务清缴证明、CNDT、联邦税务清缴证明、CRF/FGTS，并通过访问密钥下载 NF-e XML 的可读副本（不含数字签名），使用的是你的 FiscalAPI 账户。

地址： https://mcp.fiscalapi.com.br/mcp（Streamable HTTP）

两个工具无需密钥且免费：validar_inscricao_estadual 和 cobertura。其他工具使用你的 FiscalAPI 密钥，并从账户余额扣费，与 REST API 相同。

要查询真实数据：请在 app.fiscalapi.com.br 创建密钥（每月免费查询 IE/CNPJ 10 次）。

配置

密钥放在 header X-API-Key 中（也接受 Authorization: Bearer <chave>）。请将 fapi_sua_chave 替换为你的密钥。

Claude Code

claude mcp add --transport http fiscalapi https://mcp.fiscalapi.com.br/mcp --header "X-API-Key: fapi_sua_chave"

为了不让密钥留在终端历史记录中，请将其保存到环境变量，并使用 --header "X-API-Key: $FISCALAPI_API_KEY"。

Cursor

项目中的 .cursor/mcp.json 或全局的 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "fiscalapi": {
      "url": "https://mcp.fiscalapi.com.br/mcp",
      "headers": {
        "X-API-Key": "${env:FISCALAPI_API_KEY}"
      }
    }
  }
}

VS Code

.vscode/mcp.json。VS Code 会在首次使用时提示输入密钥，并安全保存：

{
  "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}"
      }
    }
  }
}

ChatGPT（开发者模式）

使用 URL https://mcp.fiscalapi.com.br/mcp 创建连接器，无需身份验证。ChatGPT 连接器只支持 OAuth 或不进行身份验证，不支持在 header 中传入 API 密钥，因此在 ChatGPT 中只能使用无需密钥的工具（validar_inscricao_estadual 和 cobertura）。如需付费查询，请使用会发送 header 的客户端，例如上面提到的客户端。

工具

每次查询的余额价格按套餐计算（套餐额度内；充值价格见括号）：Lite R$ 0,67；Starter R$ 0,10（R$ 0,12）；Pro R$ 0,065（R$ 0,07）；Enterprise R$ 0,025（R$ 0,02）。以错误结束的查询不收费；未找到登记号、返回 sem_certidao 或 nao_contribuinte 的响应均计为一次查询。

工具	功能	费用
validar_inscricao_estadual	检查州级纳税人登记号（IE）在该州的格式和校验位。不表示该 IE 是否存在或处于有效状态。	无需密钥，免费
cobertura	FiscalAPI 按产品和州提供的查询范围，以及 API 的限制。	无需密钥，免费
consultar_ie	按 CPF、CNPJ 或 IE 查询某州的州级纳税人登记号（按 CPF 查询时，涵盖除 SP 外的所有州）。	1 次查询
consultar_ie_todos_estados	一次调用即可查询 27 个州的登记号，按 CPF、CNPJ 或 IE 查询。	1 次查询（不计入免费次数）
consultar_cnpj	Receita Federal 的公开 CNPJ 登记信息，包含 Simples 和 MEI。ao_vivo=true 会实时查询。	1 次查询；实时查询为 3 次
consultar_cnd_estadual	查询某州 CPF 或 CNPJ 的州级税务清缴证明（ICMS）。	1 次查询
consultar_cndt	劳动债务清缴证明。	1 次查询
consultar_cnd_federal	联邦税务及联邦政府活跃债务清缴证明。	1 次查询
consultar_crf_fgts	FGTS 合规证明。	1 次查询
baixar_xml_nfe_sem_certificado	通过访问密钥下载 NF-e（型号 55）XML 的可读副本，不含数字签名。	3 次查询（Enterprise 为 2 次）；最低 R$ 0,05
saldo	查看余额还能用于多少次查询和多少张发票。	不消耗查询次数

每月 10 次免费查询仅适用于查询某一州的 IE 和 CNPJ（不适用于查询所有州的 IE 或实时查询 CNPJ）；账户必须从未订阅过、已确认电子邮箱且没有充值。无证书下载 NF-e XML 也会对未找到发票的访问密钥收费（但紧接着重复查询同一密钥除外），且不计入免费次数。

证书 PDF 不会通过 MCP 返回（文件对模型来说太大）。使用 REST API 时，PDF 会包含在 pdf_base64 字段中；在那里重复查询会再次收费。

限制

• 所有收费工具都有参数 confirmo_custo。如果没有 confirmo_custo=true，工具只会说明费用，不会查询任何内容。Agent 应展示费用并等待你确认。
• 此服务每个密钥每小时最多接受 30 次付费查询（被 API 拒绝的密钥不计入）。如需更大用量，请直接使用 REST API。
• 你的账户限制也同样适用：每分钟查询次数分别为 Lite 5 次、Starter 20 次、Pro 60 次和 Enterprise 120 次；无证书的 NF-e XML 查询最多可同时进行 2 次。

安全性

• 密钥只会在每次调用时通过 X-API-Key 标头传递给 FiscalAPI API（https://api.fiscalapi.com.br）。服务端没有数据库，不会记录标头，也不会保存密钥：为统计每小时上限，服务端只在内存中保存密钥的哈希值（SHA-256）；1 小时窗口结束后（或密钥被 API 拒绝时）便会丢弃该哈希值。
• 服务端只与 api.fiscalapi.com.br 通信；请求路径在代码中固定，你提供的内容会作为参数传递。
• 代码位于此处，采用 MIT 许可证。

开发

需要 uv 和 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)

测试不会真正调用 API：响应均为模拟结果。

许可证

MIT。请参阅 LICENSE。