Mexico Invoices (CFDI 4.0 factura electrónica)

Official4 toolsLive

by junter1989k-ai · JavaScript

Mexico CFDI 4.0 invoices for AI agents - issue, query, cancel facturas via Facturapi.

Topics

ai-agentscfdie-invoicefacturapiinvoicingmcpmcp-servermexicoai-agentclaudeinvoicetaxwishpool

Captured live from the server via tools/list.

create_invoice

Issue a Mexico CFDI 4.0 electronic invoice (factura electrónica, stamped/timbrada through a SAT-certified PAC). Two interchangeable PACs behind one tool (bring your own credentials as HTTP headers; this server stores nothing, and the CSD certificate stays in the merchant's own PAC account): (A) FACTURAPI — header x-facturapi-key (free sk_test_ from facturapi.io never reaches SAT; sk_live_ stamps real CFDIs). (B) FACTURAMA API-Web — headers x-facturama-user + x-facturama-password (your Facturama login) plus x-facturama-expedition-place (your branch-office 5-digit ZIP, which Facturama requires for the issuer); add x-facturama-sandbox: true for the no-fiscal-effect sandbox. Routing: whichever credential headers you send picks the PAC; if both are present Facturapi wins unless you set header x-invoice-provider: facturama. Sensible SAT defaults: product_key 01010101 (generic), payment_form 03 (bank transfer), use G03 (general expenses); item price is tax-inclusive (16% IVA assumed). For a buyer without RFC use tax_id XAXX010101000 with tax_system 616 and use S01.

Parameters8

customer_legal_name	string	required	Buyer legal name (razón social) exactly as registered with SAT — must match the RFC or SAT rejects the stamp.
customer_tax_id	string	required	Buyer RFC, e.g. ABC680524P76. Generic consumer: XAXX010101000.
customer_zip	string	required	Buyer tax-address ZIP code (código postal fiscal), 5 digits — CFDI 4.0 requires it to match SAT records.
customer_tax_system	string	optional	Buyer régimen fiscal SAT code. Default 601 (General de Ley Personas Morales). Use 616 for the generic consumer RFC.
customer_email	string	optional	Optional buyer email — stored on the invoice so send_invoice can deliver the PDF+XML.
items	array	required	Line items. Each: description, price (MXN, tax-inclusive by default), optional quantity (default 1) and product_key (SAT catalog code, default 01010101).
payment_form	string	optional	SAT forma de pago code. Default 03 (transferencia). Common: 01 cash, 04 credit card, 28 debit card, 99 por definir.
use	string	optional	SAT uso del CFDI code. Default G03 (gastos en general). Use S01 with the generic RFC.

Raw schema

{
  "type": "object",
  "properties": {
    "customer_legal_name": {
      "type": "string",
      "description": "Buyer legal name (razón social) exactly as registered with SAT — must match the RFC or SAT rejects the stamp."
    },
    "customer_tax_id": {
      "type": "string",
      "description": "Buyer RFC, e.g. ABC680524P76. Generic consumer: XAXX010101000."
    },
    "customer_zip": {
      "type": "string",
      "description": "Buyer tax-address ZIP code (código postal fiscal), 5 digits — CFDI 4.0 requires it to match SAT records."
    },
    "customer_tax_system": {
      "type": "string",
      "description": "Buyer régimen fiscal SAT code. Default 601 (General de Ley Personas Morales). Use 616 for the generic consumer RFC."
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email — stored on the invoice so send_invoice can deliver the PDF+XML."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "description": "Line items. Each: description, price (MXN, tax-inclusive by default), optional quantity (default 1) and product_key (SAT catalog code, default 01010101).",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "description": "Unit price in MXN."
          },
          "quantity": {
            "type": "number",
            "description": "Default 1."
          },
          "product_key": {
            "type": "string",
            "description": "SAT product/service catalog code. Default 01010101 (no specific code)."
          }
        },
        "required": [
          "description",
          "price"
        ]
      }
    },
    "payment_form": {
      "type": "string",
      "description": "SAT forma de pago code. Default 03 (transferencia). Common: 01 cash, 04 credit card, 28 debit card, 99 por definir."
    },
    "use": {
      "type": "string",
      "description": "SAT uso del CFDI code. Default G03 (gastos en general). Use S01 with the generic RFC."
    }
  },
  "required": [
    "customer_legal_name",
    "customer_tax_id",
    "customer_zip",
    "items"
  ]
}

query_invoice

Check a Mexico CFDI invoice created by create_invoice. Status values: VALID (stamped and fiscally valid — uuid is the SAT folio fiscal), CANCELED (voided at SAT); cancellation_status pending means SAT is still processing a cancellation. Safe to call anytime.

Parameters1

invoice_id

string

required

The invoice_id returned by create_invoice

Raw schema

{
  "type": "object",
  "properties": {
    "invoice_id": {
      "type": "string",
      "description": "The invoice_id returned by create_invoice"
    }
  },
  "required": [
    "invoice_id"
  ]
}

cancel_invoice

Cancel (void) a stamped Mexico CFDI at SAT. SAT requires a cancellation motive code: 01 replaced-with-corrected, 02 issued-in-error-no-replacement (default), 03 transaction-did-not-happen, 04 related-to-global-invoice. Some cancellations need the buyer's acceptance — status stays pending until SAT resolves it.

Parameters2

invoice_id	string	required	The invoice_id returned by create_invoice
motive	string	optional	SAT cancellation motive. Default 02.

Raw schema

{
  "type": "object",
  "properties": {
    "invoice_id": {
      "type": "string",
      "description": "The invoice_id returned by create_invoice"
    },
    "motive": {
      "type": "string",
      "enum": [
        "01",
        "02",
        "03",
        "04"
      ],
      "description": "SAT cancellation motive. Default 02."
    }
  },
  "required": [
    "invoice_id"
  ]
}

send_invoice

Email the stamped CFDI (PDF + XML) to the buyer via the same PAC that issued it (Facturapi or Facturama). Uses the email stored on the invoice unless a different one is passed.

Parameters2

invoice_id	string	required	The invoice_id returned by create_invoice
email	string	optional	Optional recipient email; defaults to the customer email on the invoice.

Raw schema

{
  "type": "object",
  "properties": {
    "invoice_id": {
      "type": "string",
      "description": "The invoice_id returned by create_invoice"
    },
    "email": {
      "type": "string",
      "description": "Optional recipient email; defaults to the customer email on the invoice."
    }
  },
  "required": [
    "invoice_id"
  ]
}

README.md4 KBView on GitHub

Mexico Invoice MCP 🇲🇽 — How can my AI agent issue a CFDI factura electrónica in Mexico?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "mexico-invoice": {
      "type": "http",
      "url": "https://inv-mx.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/mexico-invoice-mcp && cd mexico-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent issue Mexico CFDI 4.0 electronic invoices (factura electrónica, stamped/timbrada through a SAT-certified PAC) via two interchangeable PACs behind one tool set — Facturapi and Facturama. Stateless, bring-your-own credentials, never stores anything. (One PAC going down, changing its API, or raising prices no longer breaks your invoicing — send the other PAC's credentials and keep issuing.)

Live endpoint: https://inv-mx.wishpool.app/mcp · Registry: app.wishpool/mexico-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "mexico-invoice": {
      "type": "http",
      "url": "https://inv-mx.wishpool.app/mcp",
      "headers": { "x-facturapi-key": "sk_test_..." }
    }
  }
}

Free sk_test_ keys from facturapi.io never reach SAT. Your CSD certificate stays in your own Facturapi account — this server never sees it.

Or use Facturama (API-Web) instead — send these headers and requests route to Facturama automatically:

json

"headers": {
  "x-facturama-user": "your_facturama_user",
  "x-facturama-password": "your_facturama_password",
  "x-facturama-expedition-place": "01000",
  "x-facturama-sandbox": "true"
}

x-facturama-expedition-place is your Facturama branch-office 5-digit ZIP (the issuer ZIP, which Facturama requires). x-facturama-sandbox: true targets the no-fiscal-effect sandbox; drop it for production. If you send both PACs' credentials, Facturapi wins unless you add x-invoice-provider: facturama. Your CSD certificate stays in your own Facturama account (API-Web) — this server never sees it. Facturama's multi-emisor mode (self-managed certificates) is intentionally not supported: it would require handling certificates, which this pure-forwarding layer avoids.

Tools

Tool	What it does
`create_invoice`	Stamp a CFDI 4.0 — customer RFC + zip + line items in, `uuid` (SAT folio fiscal) out. SAT catalog defaults baked in (`product_key 01010101`, `payment_form 03`, `use G03`).
`query_invoice`	Status check: `VALID` (stamped) or `CANCELED`; includes SAT `verification_url`.
`cancel_invoice`	Void at SAT with the required motive code (`01`–`04`, default `02`).
`send_invoice`	Email the stamped PDF + XML to the buyer via the issuing PAC.

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them.

Develop

bash

node test/serve.js   # local server on :3226
node test/e2e.js     # protocol + validation + fake-key live probes

Safety

Pure stateless translation layer. The SAT/PAC certification burden sits with the PAC (Facturapi or Facturama); credentials travel per-request in headers, nothing is stored. Privacy policy.

Sister servers

Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included. More invoice countries coming: Brazil NF-e · Chile DTE · Peru CPE · India GST · Poland KSeF · Romania e-Factura · Italy SdI.

MIT licensed.

Install

Tools (4)

create_invoicequery_invoicecancel_invoicesend_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-mx.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mexico-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-mx.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.