Sifende

@sifende/mcp

Sifende の公式 MCP サーバーです。Claude、Cursor などの MCP クライアントを Sifende アカウントに接続すると、これまで API で行っていた操作を自然言語で依頼できます。たとえば、SIFEN の電子文書の照会、KuDE のダウンロード、納税者登録簿での RUC 検索、また有効にした場合は、請求書、ノート、イベントの発行が可能です。

• 自分のマシン上で、独自の API キーを使って stdio 経由で動作します。中継サーバーはなく、データが第三者に送信されることもありません。
• 読み取り専用で起動します。発行を行うには、環境変数で有効にする必要があります。
• 公式 SDK @sifende/sdk を使用します。API と同じ安全な再試行、冪等性、合計計算機能を備えています。

はじめに

Node.js 22.18 以降と MCP クライアントが必要です。インストールは不要です。クライアントが npx でサーバーを実行します。

1. Sandbox API キーを作成する

Sifende のダッシュボードで API Keys → Crear API Key を開き、Sandbox の API キーを作成します。キーは sk_sandbox_ で始まります（ガイド）。このキーを使うと、SIFEN に送信せずに発行を試せます。

2. クライアントにサーバーを追加する

Claude Code

claude mcp add sifende --env SIFENDE_API_KEY=sk_sandbox_... -- npx -y @sifende/mcp

Claude Desktop。「設定」→「開発者」→「設定を編集」を開き、このブロックを claude_desktop_config.json に追加してから、Claude Desktop を再起動します。

{
  "mcpServers": {
    "sifende": {
      "command": "npx",
      "args": ["-y", "@sifende/mcp"],
      "env": {
        "SIFENDE_API_KEY": "sk_sandbox_..."
      }
    }
  }
}

Cursor。 同じブロックを ~/.cursor/mcp.json に記述します。1つのプロジェクトだけで使う場合は .cursor/mcp.json に記述します。mcpServers 形式を使うほかのクライアント（Windsurf、Cline、独自形式の Zed など）でも利用できます。

3. クエリを試す

どの環境に接続されていて、プランで残り何件の文書を利用できますか？

モデルは informacion_servidor と consultar_consumo_plan を呼び出します。「Sandbox」と応答すれば、正常に動作しています。

4. テスト用の請求書を初めて発行する

モデルが発行できるようにするには、env ブロックに SIFENDE_MCP_ALLOW_WRITE=true を追加して、クライアントを再起動します。

"env": {
  "SIFENDE_API_KEY": "sk_sandbox_...",
  "SIFENDE_MCP_ALLOW_WRITE": "true"
}

Claude Code では、--env SIFENDE_MCP_ALLOW_WRITE=true を指定してサーバーを再度追加します（先に claude mcp remove sifende で削除してください）。

その後、次のように依頼します。

Juan Pérez（身分証番号 1234567）宛てに、Tシャツ2枚を各150,000 Gs、送料25,000 Gs、IVA 10%で現金払いの請求書を発行してください。承認されたら、KuDE をダウンロードしてください。

モデルは calcular_totales で合計を計算し、listar_enumeraciones で有効な値を確認してから発行します。その後、SIFEN が承認するまで状態を確認し、PDF を保存します。発行前にクライアントで確認を求められます。

環境

API キーのプレフィックスで環境が決まります。別の URL や設定は不要です。

プレフィックス	環境	税務上の有効性	イベント（取消、無効化、指名）
sk_sandbox_	Sifende Sandbox。SIFEN には送信されません。	なし	なし。イベント用ツールは表示されません。
sk_test_	SIFEN のテスト環境。	なし	あり
sk_live_	本番環境。	あり	あり

イベントを試すには、sk_test_ の API キーを使用します。サーバーがどの環境に接続されているか確認するには、モデルに尋ねるか、informacion_servidor を呼び出してください。

依頼できること

照会（常に利用できます）：

CDC 01800123450010010000001... の文書の状態はどうなっていますか？

登録簿で RUC 80012345 を検索して、商号を教えてください。

文書 01800123450010010000001... の KuDE をダウンロードしてください。

SIFEN で使用できる測定単位コードを教えてください。

書き込みを有効にした場合：

CDC 01800123450010010000001... の請求書をキャンセルしてください。顧客から返品されました。

スタンプ番号 12345678、事業所 001、発行拠点 001 の請求書 50～60 番を無効化してください。システムエラーで発行されませんでした。

前の請求書に含まれる T シャツのうち 1 枚が返品されたので、クレジットノートを作成してください。

sk_live_ を使用する前に

API キー sk_live_ を使うと、発行する文書はすべて納税者名義の実際の税務書類になります。

• 各操作を監督してください。 モデルは金額、受取人、文書の種類を間違えることがあります。SIFEN に承認された文書を取り消せるのは、48 時間以内（請求書）または 168 時間以内（ノート）にキャンセルした場合のみです。
• 書き込みツールを承認する前にデータを確認してください。 MCP クライアントはツールごとに確認を求めます。sk_live_ を使用する場合は、この確認を無効にしないでください。
• 照会のみを行う場合は、SIFENDE_MCP_ALLOW_WRITE をオフにしてください。 書き込みを有効にして sk_live_ で起動すると、サーバーは stderr に警告を書き込みます。
• API キーはパスワードとして扱ってください。 クライアントの設定に平文で保存されます。リポジトリにアップロードしないでください。
• サーバーは自分のマシン上でのみ実行してください。 ネットワークに公開したり、配布するアプリに含めたりしないでください。

リファレンス

環境変数

変数	デフォルト	説明
SIFENDE_API_KEY		必須です。プレフィックスで環境が決まります。
SIFENDE_MCP_ALLOW_WRITE	false	true または 1 にすると、文書やイベントを発行するツールが表示されます。true、1、false、0、または空の値を受け付けます。それ以外の値では、サーバーは起動しません。
SIFENDE_MCP_KUDE_DIR	システムの一時フォルダー	descargar_kude が PDF を保存するフォルダーです。
SIFENDE_BASE_URL	https://api.sifende.com.py	別のホストを指定する場合にのみ使用します。

読み取りツール

常に利用できます。

ツール	説明
informacion_servidor	環境、バージョン、書き込みが有効かどうかを確認します。ネットワークは使用しません。
consultar_documento	CDC を指定して文書の状態（PENDIENTE、APROBADO、APROBADO_OBSERVACION、RECHAZADO、CANCELADO、ERROR）を確認し、SIFEN のプロトコルと却下理由を返します。
descargar_kude	承認済み文書の KuDE（PDF）をローカルファイルに保存し、パスを返します。任意で base64 形式でも返せます。
consultar_contribuyente	API キーに紐付く納税者の RUC、商号、環境、事業活動を返します。
consultar_padron	SET の登録簿で RUC または身分証番号を検索し、受取人のフィールド名を使ってデータを返します。
consultar_consumo_plan	現在のプランと、含まれる文書数、消費済み文書数、利用可能な文書数を返します。
listar_enumeraciones	API の各列挙型で有効な値を返します。支払方法、測定単位、通貨、国などが含まれます。
consultar_geografia	SIFEN コード付きの県、地区、市を返します。
listar_eventos / consultar_evento	登録済みイベント（キャンセル、無効化、名義指定）と、SIFEN 上の状態を返します。
calcular_totales	SET の公式の丸め規則を使って文書の合計額を計算します。API は呼び出さず、ローカルで計算します。
obtener_ejemplo_documento	架空のデータを使った文書のサンプルを返します。現金払いの B2C・B2B 請求書、分割払いの請求書、クレジットノート、デビットノートが含まれます。

書き込みツール

SIFENDE_MCP_ALLOW_WRITE=true の場合にのみ表示されます。sk_sandbox_ API キーを使用する場合、Sandbox はイベントに対応していないため、emitir_documento のみ表示されます。

ツール	内容	アノテーション
emitir_documento	請求書、クレジットノート、デビットノート、送金伝票、または自己請求書を発行します。状態が PENDIENTE の CDC を返します。	readOnlyHint: false、destructiveHint: false
cancelar_documento	承認済みの文書を取り消します（請求書は48時間以内、ノートは168時間以内）。	destructiveHint: true
inutilizar_numeracion	未使用の番号範囲を無効にします。	destructiveHint: true
nominar_documento	無記名で発行された請求書の受取人を特定します。	destructiveHint: false

emitir_documento と nominar_documento は、登録済みの内容を変更または削除せず、追加のみを行うため、破壊的な操作としてマークされていません。それでも取り消しはできません（発行済みの文書は、期限内に取り消すことでのみ無効にできます）。また、sk_live_ API キーを使用する場合、4つの説明すべてで、実際の税務処理を登録することと、ユーザーにデータを確認することをモデルに警告します。

リソース

URI	内容
sifende://guia/rapida	発行の流れ、文書のルール、イベント。
sifende://docs/llms.txt	sifende.com.py からダウンロードしたドキュメントの索引。
sifende://ejemplos/{nombre}	obtener_ejemplo_documento と同じサンプル文書。

エラー

API エラー（Problem Details、RFC 9457）は、読みやすいテキストとしてモデルに渡されます。コード、詳細、無効な各フィールド、列挙値でエラーが発生した場合の有効な値、サポート用の traceId、エラーのドキュメントへのリンクが含まれます。

イベントの発行または登録中に接続が切れた場合、処理が実行されたかどうかはわかりません。メッセージには使用された idempotencyKey が含まれます。モデルが同じ idempotencyKey を使って呼び出しを再試行すると、元の結果が返され、文書が重複して作成されることはありません。emitir_documento とイベントは、使用した idempotencyKey を必ず返します。

開発

git clone https://github.com/ithdev/sifende-mcp
cd sifende-mcp
npm ci
npm run lint && npm run typecheck && npm test && npm run build

テストでは、MCP サーバーをメモリ内で起動し、偽の fetch を使って API をシミュレートするため、ネットワークへの呼び出しは発生しません。

Inspector で試す

# Listar las herramientas
npx @modelcontextprotocol/inspector --cli -e SIFENDE_API_KEY=sk_sandbox_... node dist/index.mjs --method tools/list

# Llamar una herramienta
npx @modelcontextprotocol/inspector --cli -e SIFENDE_API_KEY=sk_sandbox_... node dist/index.mjs \
  --method tools/call --tool-name listar_enumeraciones --tool-arg nombre=tipoPago

# Interfaz web. El Inspector no hereda el entorno: pasá la API key en la interfaz o con -e.
SIFENDE_API_KEY=sk_sandbox_... npm run inspector

バージョンの公開

npm と MCP Registry で公開する手順は、RELEASING.md に記載されています。

サポート

• MCP サーバーのエラー：issue を作成してください。
• 脆弱性：SECURITY.md の説明に従って、非公開で報告してください。
• アカウント、文書、API に関するお問い合わせ：[email protected] までご連絡ください。

ライセンス

Apache 2.0。Copyright 2026 ITH E.A.S.。NOTICE を参照してください。