fattureincloud-mcp

fattureincloud-mcp

Mediaform s.c.r.l. 制作 — イタリア、ジェノヴァ

Claude（Desktop、Code、または任意の MCP クライアント）を、イタリアを代表する電子請求書発行 SaaS FattureInCloud に接続する MCP サーバーです。自然言語を使って、請求書、クレジットノート、プロフォーマ、クライアント、仕入先、費用／収益センター、仕入先経費を管理できます。イタリアでは、Sistema di Interscambio（SDI）を通じた B2B／B2C の電子請求が義務付けられています。このサーバーは、コンプライアンスが重視される業務に AI を活用した請求処理をもたらします。

⚠️ 非公式の連携です。 FattureInCloud の商標所有者である TeamSystem S.p.A. とは提携しておらず、同社からの承認や支援も受けていません。ここで商標を使用しているのは、説明を目的としたものです。

機能（23 個のツール）

ツール	説明
list_invoices	年／月ごとに発行済みの請求書／クレジットノート／プロフォーマを一覧表示します
get_invoice	ID を指定して書類の詳細をすべて取得します
get_pdf_url	書類の PDF URL と Web リンクを取得します
list_clients	オプションのフィルターを指定してクライアントを一覧表示します
get_company_info	接続中の会社情報を取得します
create_client	新しいクライアントを作成します
update_client	既存のクライアントを更新します
create_invoice	下書きの請求書を作成します（revenue_center は任意）
create_credit_note	下書きのクレジットノートを作成します（revenue_center は任意）
create_proforma	下書きのプロフォーマを作成します（revenue_center は任意）
convert_proforma_to_invoice	プロフォーマを下書きの電子請求書に変換します（revenue_center は任意）
update_document	下書き書類を部分更新します（revenue_center は任意）
duplicate_invoice	新しい日付で請求書を複製します（revenue_center は任意）
delete_invoice	下書き書類を削除します
send_to_sdi	請求書／クレジットノートをイタリアの電子請求書システム（SDI）に送信します
get_invoice_status	書類の電子請求書ステータスを取得します
send_email	控えをメールで送信します
list_received_documents	仕入先書類を一覧表示します（該当する場合は cost_center を表示）
get_received_document	ID を指定して受領書類の詳細をすべて取得します
create_received_document	受領書類／経費を作成します（cost_center は任意）
list_cost_centers	設定済みの費用／収益センターを一覧表示します
get_situation	年次ダッシュボード：純収益、回収額、未回収額、費用、利益率
check_numeration	請求書番号の連続性を確認します

支払いを「支払済み」として記録する機能は、意図的に公開していません。FattureInCloud API では支払い口座が必要ですが、SDK を通じて確実に取得できないためです。この操作には FattureInCloud の Web パネルを使用してください。

インストール

オプション 1 — Claude Desktop（MCPB バンドル、推奨）

1. GitHub リリースページから最新の fattureincloud.mcpb をダウンロードします。
2. .mcpb ファイルを Claude Desktop にドラッグするか、Settings → Extensions → Install from file を選択します。
3. プロンプトが表示されたら、FattureInCloud API トークン、会社 ID、（任意の）送信者メールアドレスを入力します。

これで完了です。Python のセットアップも仮想環境も不要です。

オプション 2 — PyPI から手動でインストール

Claude Code ユーザー、または claude_desktop_config.json 形式の設定ファイルを読み込む任意の MCP クライアント向けです。

pip install fattureincloud-mcp

次に、MCP クライアントの設定に追加します（Claude Desktop の場合、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json）。

{
  "mcpServers": {
    "fattureincloud": {
      "command": "python",
      "args": ["-m", "fattureincloud_mcp"],
      "env": {
        "FIC_ACCESS_TOKEN": "a/xxxxx.yyyyy.zzzzz",
        "FIC_COMPANY_ID": "123456",
        "FIC_SENDER_EMAIL": "[email protected]"
      }
    }
  }
}

設定を編集した後、MCP クライアントを再起動してください。

設定

環境変数	必須	説明
FIC_ACCESS_TOKEN	はい	個人用 API アクセストークン（a/ で始まります）
FIC_COMPANY_ID	はい	数値の会社 ID。FattureInCloud にログインすると URL に表示されます
FIC_SENDER_EMAIL	send_email に必須	控え用メールの送信者メールボックス
FIC_CACHE_DIR	いいえ	キャッシュディレクトリを上書きします（既定値は ~/.fattureincloud-mcp/cache）
FIC_CACHE_DISABLED	いいえ	1 に設定するとローカルキャッシュが無効になります

FattureInCloud の認証情報を取得する方法： FattureInCloud にログインし、設定 → API と連携 に移動して、必要な権限を持つ 手動トークン を作成します。会社を選択すると、COMPANY_ID は URL の /c/ の後に表示されます。

使用例

例 1 — 既知のクライアント向けに請求書を作成する

「クライアント『Acme Srl』を検索し、2026 年 11 月のコンサルティングサービスについて、€1,500 ＋ VAT の下書き請求書を作成してください。支払い期限は 30 日後、売上センターは『Project Alpha』です。」

Claude は次の操作を行います。

1. list_clients を呼び出し（キャッシュ済み）、該当するクライアントを選択します
2. list_cost_centers を呼び出し（キャッシュ済み）、Project Alpha が存在することを確認します
3. client_id、項目、日付、支払い条件、および revenue_center="Project Alpha" を指定して create_invoice を呼び出します
4. 下書き番号を返し、SDI に送信するかどうかを尋ねます

例 2 — コストセンター分析

「2025 年に『Project Alpha』の売上センターでいくら請求しましたか？月ごとに内訳を表示してください。」

Claude は次の操作を行います。

1. list_cost_centers を呼び出してラベルを確認します
2. 2025 年を指定して list_invoices を呼び出します（設定されている場合、結果には請求書ごとの revenue_center が含まれます）
3. revenue_center == "Project Alpha" で絞り込み、月ごとに集計します

例 3 — 定期請求書の再作成

「2025 年 10 月に『Recurring Customer Co』宛てに発行された請求書をすべて複製し、新しい日付を 11 月に設定して、支払い条件は 30 日のままにしてください。」

Claude は次の操作を行います。

1. query="Recurring Customer Co"、month=10、year=2025 を指定して list_invoices を呼び出します
2. 結果ごとに、new_date を 11 月の日付に設定して duplicate_invoice を呼び出します
3. 新しい下書き請求書の一覧を返し、送信前に確認を求めます

キャッシュ

FattureInCloud API への重複した呼び出しを最小限に抑えるため、このサーバーはクライアント検索結果とコストセンター一覧を JSON ファイルとしてローカルにキャッシュします（既定の保存先は ~/.fattureincloud-mcp/cache/ で、company_id ごとに分けられ、有効期間は 24 時間です）。キャッシュは透過的に機能し、ツールのシグネチャは変わりません。

# Force refresh:
rm -rf ~/.fattureincloud-mcp/cache

# Disable temporarily:
export FIC_CACHE_DISABLED=1

コストセンター／売上センター

FattureInCloud では、コストセンター（仕入先書類）と売上センター（発行済み書類）に共通のレジストリを使用します。このサーバーでは、次の操作ができます。

• list_cost_centers — レジストリを読み取ります
• revenue_center="<label>" — create_invoice、create_credit_note、create_proforma、convert_proforma_to_invoice、update_document、duplicate_invoice で割り当てます
• cost_center="<label>" — create_received_document で割り当てます

ラベルはすでに存在している必要があります。センターは FattureInCloud のウェブ UI（設定 → コストセンター）で管理します。不明なラベルを渡すと、エラーメッセージに有効なラベルの一覧が返されます。

プライバシーとデータの取り扱い

• API 呼び出しは、お使いのマシンから FattureInCloud のサーバー（api-v2.fattureincloud.it）へ直接送信されます。Mediaform やサードパーティのサーバーを経由してデータが送信されることはありません。
• ローカルキャッシュはホームディレクトリに保存されるプレーンテキストの JSON です。管理はお客様ご自身で行えます。
• 認証情報は .env（gitignore 対象）、シェル、または MCP クライアントの user_config のみに保存されます。ログに記録されたり、FattureInCloud 以外に送信されたりすることはありません。
• プライバシーポリシー全文：https://media-form.it/privacy-policy.html
• ポリシーのミラーコピーについては、docs/PRIVACY.md もご覧ください。

既知の問題

• 一部のクライアントでは請求書の複製に失敗する場合があります。 特定のクライアント設定で、まだ再現できていない失敗経路が発生します。回避策：FattureInCloud のウェブパネルから手動で複製してください。詳細は docs/KNOWN_ISSUES.md で追跡しています。再現可能なケースは GitHub issues から報告してください。

コントリビューション

https://github.com/aringad/fattureincloud-mcp へのイシューやプルリクエストを歓迎します。

コードを変更する場合は、次の手順に従ってください。

1. main からフォークし、ブランチを作成します（feat/...、fix/...、docs/...）。
2. pytest tests/ を実行します。39 件すべてのテストが成功する状態を維持してください。
3. コストセンター、キャッシュ、新しいツールを対象とする新しいコードには、テストを含めてください（新しいモジュールのカバレッジ目標は 80% 以上です）。
4. Conventional Commits の形式を使用します（feat:、fix:、docs:、chore:、test:）。
5. PR を作成します。メンテナーが FattureInCloud API の仕様に照らして変更をレビューします。

セキュリティ

脆弱性の報告については SECURITY.md をご覧ください。推奨する窓口：GitHub Security Advisories。

ライセンス

MIT — LICENSE をご覧ください。

商標

「FattureInCloud」は TeamSystem S.p.A. の商標です。本ソフトウェアは独立したコミュニティ開発の連携ツールです。TeamSystem S.p.A. との提携、承認、またはスポンサー関係はありません。この商標は、本ソフトウェアが連携するサードパーティサービスを示すためにのみ使用しています。

作者／サポート

• メンテナー：Mediaform s.c.r.l. — イタリア、ジェノヴァ
• イシュー：https://github.com/aringad/fattureincloud-mcp/issues
• メール：[email protected]