mcp-nuvem-fiscal

@codespar/mcp-nuvem-fiscal

Nuvem Fiscal 用 MCP サーバー — NFe、NFSe、NFCe の税務書類発行と CNPJ／CEP の照会

クイックスタート

Claude Desktop

~/.config/claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "nuvem-fiscal": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nuvem-fiscal"],
      "env": {
        "NUVEM_FISCAL_CLIENT_ID": "your-client-id",
        "NUVEM_FISCAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

claude mcp add nuvem-fiscal -- npx @codespar/mcp-nuvem-fiscal

Cursor ／ VS Code

.cursor/mcp.json または .vscode/mcp.json に追加します。

{
  "servers": {
    "nuvem-fiscal": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nuvem-fiscal"],
      "env": {
        "NUVEM_FISCAL_CLIENT_ID": "your-client-id",
        "NUVEM_FISCAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

ツール（24）

ツール	用途
create_nfe	NF-e（電子税務請求書）を作成
get_nfe	ID で NF-e の詳細を取得
cancel_nfe	NF-e をキャンセル
create_nfse	NFS-e（電子サービス税務請求書）を作成
get_nfse	ID で NFS-e の詳細を取得
cancel_nfse	NFS-e をキャンセル
create_nfce	NFC-e（電子消費者税務請求書）を作成
consult_cnpj	CNPJ 番号で企業情報を照会
consult_cep	CEP（郵便番号）で住所を照会
register_company	Nuvem Fiscal に企業を登録
create_cte	CT-e（電子運輸書類）を作成
get_cte	ID で CT-e の詳細を取得
cancel_cte	CT-e をキャンセル
create_mdfe	MDF-e（電子税務書類マニフェスト）を作成
get_nfe_events	NF-e のイベント（キャンセル、訂正など）を取得
cancel_nfce	NFC-e（電子消費者税務請求書）をキャンセル
send_correction_letter_nfe	NF-e の電子訂正書（CCe）を送信
send_correction_letter_cte	CT-e の訂正書を送信
get_nfe_batch	バッチ ID で NF-e バッチ（ロット）のステータスを取得
get_mdfe	ID で MDF-e の詳細を取得
cancel_mdfe	MDF-e（マニフェスト）をキャンセル
close_mdfe	ルートの終点で MDF-e を終了
list_empresas	アカウントに登録されているすべての企業（empresas）を一覧表示
upload_certificate	企業（empresa）の A1 デジタル証明書（.pfx、base64）をアップロードまたは更新

認証

Nuvem Fiscal は OAuth2 クライアント認証情報を使用します。サーバーがトークンの更新を自動的に管理します。

サンドボックス／テスト

Nuvem Fiscal は、実際の税務システムに影響を与えずに税務書類の発行をテストできる、検証環境（ambiente=2）をサポートしています。

デモモード

MCP_DEMO=true を設定するか、--demo を渡すと、Nuvem Fiscal API に接続せずにサーバーを実行できます。MCP_DEMO=true モードでは、create_nfse は同一プロセス内で呼び出しごとに異なるフィクスチャ ID を発行し、入力された servico.codigo、valor、servico.descricao をレスポンスに反映します。pdf_url はフィクスチャ ID をもとに生成されます。その他のデモツールは静的なフィクスチャを返すため、オフラインでの操作確認や統合スモークテストに役立ちます。

認証情報を取得する

1. Nuvem Fiscal Developer Portal にアクセスします
2. アカウントを作成します
3. アプリケーションを登録して OAuth2 認証情報を取得します
4. 環境変数を設定します

環境変数

変数	必須	説明
NUVEM_FISCAL_CLIENT_ID	はい	OAuth2 クライアント ID
NUVEM_FISCAL_CLIENT_SECRET	はい	OAuth2 クライアントシークレット

ロードマップ

v0.2（予定）

• create_cte — CT-e（電子運輸書類）を作成
• get_cte — ID で CT-e の詳細を取得
• cancel_cte — 発行済みの CT-e をキャンセル
• create_mdfe — MDF-e（電子貨物マニフェスト）を作成
• get_nfe_events — NF-e のイベント（キャンセル、訂正など）を取得

v0.3（予定）

• batch_nfe — 1 回のリクエストで複数の NF-e を作成
• get_nfe_danfe — NF-e の DANFE PDF を取得
• manifest_recipient — NF-e の受領者が受領を認識したことを表明

貢献をご希望ですか？PR を送信するか、ツールをリクエストしてください。

リンク

• Nuvem Fiscal のウェブサイト
• Nuvem Fiscal API ドキュメント
• MCP Dev LATAM
• ランディングページ

エンタープライズ

エージェントによる支払いにガバナンス、予算上限、監査証跡が必要ですか？CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、支払いルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT