verifactu-mcp

verifactu-mcp

Claude Code および Cursor と VeriFactu（AEAT） を連携する MCP サーバーです。

AEAT の技術文書を読むことなく、自然言語で電子請求書の記録を生成、連鎖、送信できます。

---

利用可能なツール

ツール	説明
generate_invoice_xml	連鎖した SHA-256 ハッシュを含む有効な XML を生成します（送信はしません）
send_invoice	API 経由で登録記録を AEAT に送信し、ハッシュを永続化します
cancel_invoice	取消記録を送信します
check_invoice_status	記録の状態を照会します
list_invoices	送信済みの記録を一覧表示します（発行者による任意のフィルターおよびページネーションに対応）
get_last_hash	発行者についてローカルに記録された最新のハッシュを返します
calculate_hash	任意の記録の SHA-256 ハッシュを計算します

実際の連鎖処理は、内部的に verifactuapi.es の API が管理します（previous_id 経由）。MCP サーバーは、API が返す正規ハッシュをローカルの SQLite（~/.verifactu-mcp/state.db）に監査ログとして永続化します。これは運用上の連鎖処理の仕組みではありません。get_last_hash ツールはこのログを照会します。

calculate_hash と send_invoice の huella_local_estimada は、確認用のヒューリスティックな推定値です。正規の AEAT ハッシュにはサーバー側のタイムスタンプが含まれるため、生成できるのはサーバーだけです。

サンドボックスに対するスモークテスト

$env:VERIFACTU_API_TOKEN = "<tu_token_sandbox>"
python smoke_test.py <id_emisor> [nif_receptor]

list_invoices + send_invoice（サンドボックスに実際の記録を送信します！）+ check_invoice_status + get_last_hash を実行します。本番環境に対しては実行しないでください。

---

インストール

# 1. Clona el repositorio
git clone https://github.com/tuusuario/verifactu-mcp
cd verifactu-mcp

# 2. Instala las dependencias
pip install -e .

---

Claude Code の設定

pip install -e . の実行後、スクリプト verifactu-mcp がグローバルに利用可能になります。 以下を ~/.claude.json（または claude_desktop_config.json）に追加してください。

{
  "mcpServers": {
    "verifactu": {
      "command": "verifactu-mcp",
      "env": {
        "VERIFACTU_API_TOKEN": "tu_token_aqui"
      }
    }
  }
}

スクリプトをインストールせずに利用する方法（python -m 経由）：

{
  "mcpServers": {
    "verifactu": {
      "command": "python",
      "args": ["-m", "verifactu_mcp.server"],
      "cwd": "/ruta/a/verifactu-mcp",
      "env": {
        "VERIFACTU_API_TOKEN": "tu_token_aqui"
      }
    }
  }
}

---

Claude Code からの使用方法

# Generar un XML sin enviar (ideal para pruebas)
"Genera un registro VeriFactu para una factura de 100€ + 21% IVA,
 emisor B12345678, serie 2025/001, fecha 15-05-2025,
 descripción: Servicios de desarrollo web"

# Enviar a la AEAT — la huella anterior se resuelve automáticamente
"Envía a la AEAT la factura 2025/001 del emisor B12345678,
 base 100€, IVA 21%, fecha hoy"

# Consultar estado
"¿Cuál es el estado del registro con ID 42?"

# Anular una factura
"Anula la factura 2025/001 del emisor B12345678"

# Listar las facturas enviadas
"Lista las últimas 50 facturas enviadas para el emisor B12345678"

# Inspeccionar el último hash del emisor
"¿Cuál es la última huella encadenada para B12345678?"

---

環境変数

変数	説明	必須
VERIFACTU_API_TOKEN	verifactuapi.es へのアクセストークン	はい（送信する場合）
VERIFACTU_API_BASE	API のベース URL（デフォルトは本番環境）	いいえ
VERIFACTU_STATE_DB	状態を保存する SQLite DB のパス（デフォルトは ~/.verifactu-mcp/state.db）	いいえ

---

AEAT 環境

環境	URL
サンドボックス	https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP
本番環境	https://www1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP

テスト用証明書（サンドボックス）：[email protected]

---

ライセンス

MIT