FiscalAPI

FiscalAPI MCP

FiscalAPI の MCP サーバーです。AI エージェント（Claude、Cursor、VS Code、ChatGPT）から、27州の州登録番号、CNPJ、州税務証明書、CNDT、連邦税務証明書、CRF/FGTSを照会したり、アクセスキーを使って NF-e の XML を読み取り用コピーとしてダウンロードしたりできます（デジタル署名なし）。FiscalAPI のアカウントを使用します。

エンドポイント： https://mcp.fiscalapi.com.br/mcp（Streamable HTTP）

2つのツールはキー不要で、無料で利用できます：validar_inscricao_estadual と cobertura。それ以外のツールでは FiscalAPI のキーを使用し、REST API と同様にアカウント残高から料金が引き落とされます。

実際のデータを照会するには、app.fiscalapi.com.br でキーを作成してください（IE/CNPJ の照会は月10回まで無料です）。

設定

キーは 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 または認証なしのみで、ヘッダーに API キーを指定できません。そのため、ここではキー不要のツール（validar_inscricao_estadual と cobertura）のみ利用できます。有料の照会には、上記のようにヘッダーを送信できるクライアントを使用してください。

ツール

プランごとの残高からの照会1回あたりの料金（プランに含まれる利用分；チャージ分は括弧内）：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	州（UF）における IE の形式とチェックデジットを確認します。IE が存在するか、有効かは判定しません。	キー不要、無料
cobertura	FiscalAPI が製品および州（UF）ごとに照会できる内容と、API の制限を確認します。	キー不要、無料
consultar_ie	州（UF）の州登録番号を CPF、CNPJ、または IE で照会します（CPF での照会は SP を除く全州に対応）。	1回の照会
consultar_ie_todos_estados	1回の呼び出しで、27州の州登録番号を CPF、CNPJ、または IE で照会します。	1回の照会（無料枠の対象外）
consultar_cnpj	Simples および MEI の情報を含む、連邦歳入庁の CNPJ 公開登録情報を照会します。ao_vivo=true を指定すると、リアルタイムで照会します。	1回の照会；リアルタイム照会は3回分
consultar_cnd_estadual	州（UF）における 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 の1州分と CNPJ が対象です（全州の IE および CNPJ のリアルタイム照会は対象外）。アカウントは、これまで一度も契約しておらず、メールアドレスの確認が済んでいて、チャージをしていない必要があります。証明書なしの NF-e XML では、請求書が見つからなかった場合もアクセスキーの照会料金がかかります（直後に同じキーを再照会した場合を除く）。また、無料枠の対象外です。

証明書の PDF は大きすぎるため、MCP からは返されません。REST API では pdf_base64 フィールドから取得できますが、そこで再度照会すると料金がもう一度かかります。

制限

• 料金が発生するツールには、必ず confirmo_custo パラメーターがあります。confirmo_custo=true を指定しない場合、料金の説明だけを行い、何も照会しません。エージェントは料金を提示し、あなたの承認を待つ必要があります。
• このサーバーでは、キーごとに1時間あたり最大30件の有料照会を受け付けます（APIによって拒否されたキーはカウントされません）。大量に利用する場合は、REST APIを直接使用してください。
• アカウントの制限も適用されます。1分あたりの照会数は、Liteが5件、Starterが20件、Proが60件、Enterpriseが120件です。証明書を使用しないNF-eのXML照会は、同時に2件までです。

セキュリティ

• キーは各呼び出しで、X-API-Key ヘッダーを使用して FiscalAPI のAPI（https://api.fiscalapi.com.br）にのみ渡されます。サーバーにはデータベースがなく、ヘッダーを記録せず、キーも保存しません。1時間あたりの上限をカウントするために、キーのハッシュ（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をご覧ください。