nota-fiscal-mcp

🧾 nota-fiscal-mcp

AI に請求書を発行させましょう。

nota-fiscal-mcp は、あらゆる AI エージェント — Claude Desktop、Claude Code、Cursor など — に、ブラジルで NF-e と NFS-e を発行、照会、取り消す機能を提供する MCP サーバーです。税務プロバイダー（Focus NFe）と連携し、デジタル証明書、SEFAZ や市役所との通信といった難しい部分をすでに処理しています。

あなたは会話するだけ。AI が発行します。

Você:   emita uma NFS-e de R$ 500 de consultoria em TI para o cliente ACME
Claude: ✅ NFS-e emitida — nota nº 3070, autorizada. Aqui está o PDF e o XML.

システムを開く必要も、フォームに入力する必要も、ISS の項目を覚える必要もありません。

---

✨ できること

ツール	内容
emitir_nfse	サービス請求書（NFS-e）を発行します
consultar_nfse	NFS-e のステータスとリンク（XML/PDF）を照会します
cancelar_nfse	承認済みの NFS-e を取り消します
emitir_nfe	商品請求書（NF-e、モデル 55）を発行します
consultar_nfe	NF-e のステータスとダウンロード情報を照会します
cancelar_nfe	NF-e を取り消します（発行から 24 時間以内）

AI が請求書の税務情報を作成し、サーバーが認証、参照番号、プロバイダーとの通信を処理します。

---

🚀 インストール

クローンもビルドも不要です。パッケージは npx から直接実行できます。

Claude Desktop

設定ファイル（claude_desktop_config.json）を開き、次の内容を追加します。

{
  "mcpServers": {
    "nota-fiscal": {
      "command": "npx",
      "args": ["-y", "nota-fiscal-mcp"],
      "env": {
        "FOCUS_NFE_TOKEN": "seu_token_aqui",
        "FOCUS_NFE_AMBIENTE": "homologacao"
      }
    }
  }
}

Claude Desktop を再起動します。これで、エージェントに 6 つのツールが表示されます。

どの MCP クライアント（Claude Code、Cursor など）でも同じように動作します。環境変数を設定して、コマンド npx -y nota-fiscal-mcp を指定するだけです。

---

🔑 前提条件：税務プロバイダーのアカウント

実際に請求書を発行するには、税務プロバイダーのトークンが必要です。現在、nota-fiscal-mcp は Focus NFe を使用しています。テスト環境（検証環境）が提供され、デジタル証明書と SEFAZ の処理も代行してくれます。

1. Focus NFe でアカウントを作成します。
2. 会社を登録し、検証用トークンを取得します（API パネル → トークン）。
3. 上記の設定にトークンを追加して、自由にテストしてください。検証環境では、実際の税務価値を持つ請求書は発行されません。
4. 準備が整ったら、FOCUS_NFE_AMBIENTE を producao に変更し、本番用トークンを使用します。

---

⚙️ 環境変数

変数	必須	説明
FOCUS_NFE_TOKEN	はい	Focus NFe アカウントのトークン
FOCUS_NFE_AMBIENTE	いいえ	homologacao（デフォルト）または producao

---

🧪 シミュレーションモード（プロバイダー不要）

トークンなしで一連の流れをテストしたい場合は、シミュレーションモードで実行してください。応答を模擬し、6 つのツールを最初から最後まで試せます。

"env": { "PROVIDER": "mock" }

---

🔒 セキュリティ

• トークンは環境変数に設定してください。コードに直接記述したり、リポジトリにアップロードしたりしないでください。
• 必ず検証環境から始めてください。検証が済んでから、本番環境に切り替えてください。
• このプロジェクトはオープンソースです。ご自身のアカウントとご自身のトークンで実行できます。第三者のサーバーを経由することはありません。

---

🛠️ 開発

git clone https://github.com/FAVIOSENGER/nota-fiscal-mcp.git
cd nota-fiscal-mcp
npm install
npm run build
PROVIDER=mock node test/client.mjs   # testa as 6 ferramentas em simulação

---

📍 ステータス

v0.1.2 — 初の一般公開版です。Focus NFe 経由で NF-e と NFS-e をサポートしています。 ペイロードのフィールドはFocus NFe のドキュメントの規格に準拠しています。本番環境で使用する前に、お住まいの市町村の要件をご確認ください。

📖 記事／チュートリアル： MCP を使って AI に請求書（NF-e と NFS-e）を発行させる方法

アイデア、バグ報告、ご提案：issue を作成。

📄 ライセンス

MIT © Favio Senger