PixelLetter MCP

pixelletter-mcp

Servidor MCP local (stdio) para la interfaz HTTPS de PixelLetter. Entrégale un PDF y un país de destino y PixelLetter imprime, pliega, franquea y envía la carta, opcionalmente como correo certificado. También envía faxes, cancela pedidos, lee el saldo de la cuenta y gestiona la firma electrónica de facturas.

Se complementa con pdf-letter-mcp: ese servidor genera un PDF de carta según la norma DIN 5008, este lo pone en el correo. send_letter toma la ruta absoluta que devuelve create_letter.

La implementación sigue la documentación publicada: el manual HTTPS, el manual de correo electrónico, los dos manuales de firma, la clase PHP de referencia (versión 2.01) y la lista pública de códigos de error. Tres valores no aparecen en esos documentos —impresión en color, franqueo GoGreen y el interruptor NODUPLEX— y se han tomado del cliente hudora/pyPostal, que ha enviado pedidos reales con ellos. Están marcados como tales en la tabla siguiente. Nada más se ha inventado.

Cómo funciona la interfaz

Todo es una única petición HTTPS POST multiparte a https://www.pixelletter.de/xml/index.php. El campo de formulario xml lleva el documento de pedido, incluidas las credenciales, y los campos uploadfile0, uploadfile1, etc., llevan los documentos. La respuesta es un pequeño documento XML: el código 100 significa que el pedido fue aceptado; cualquier otro valor es un código de error de la lista publicada. El resultado final, incluido si la dirección del destinatario encajaba en la ventanilla de la dirección, llega por correo electrónico unas horas después.

Modo de prueba

Cada herramienta de envío necesita un indicador explícito testMode; no hay valor predeterminado. testMode: true ejecuta el pedido exactamente como uno real, pero PixelLetter nunca lo imprime, nunca lo envía y nunca lo cobra. testMode: false envía realmente la carta. Establece PIXELLETTER_FORCE_TEST_MODE=true para fijar todo el servidor en modo de prueba mientras se configura todo.

Instalación

npm install
npm run build

Registra el servidor en Claude Code:

claude mcp add pixelletter \
  --env PIXELLETTER_EMAIL=you@example.com \
  --env PIXELLETTER_PASSWORD=your-password \
  -- node "/absolute/path/to/pixelletter-mcp/dist/src/index.js"

O en ~/.claude.json / claude_desktop_config.json:

{
  "mcpServers": {
    "pixelletter": {
      "command": "node",
      "args": ["/absolute/path/to/pixelletter-mcp/dist/src/index.js"],
      "env": {
        "PIXELLETTER_EMAIL": "you@example.com",
        "PIXELLETTER_PASSWORD": "your-password",
        "PIXELLETTER_DEFAULT_DESTINATION": "DE"
      }
    }
  }
}

Entorno

Variable	Propósito
PIXELLETTER_EMAIL	Obligatoria. La dirección de correo electrónico con la que está registrada la cuenta de PixelLetter.
PIXELLETTER_PASSWORD	Obligatoria. La contraseña de PixelLetter.
PIXELLETTER_ENDPOINT	Punto final de la interfaz. Valor predeterminado https://www.pixelletter.de/xml/index.php.
PIXELLETTER_ACCEPT_TERMS	Acepta los términos de PixelLetter con cada pedido; valor predeterminado true. La API rechaza los pedidos en caso contrario (error 013).
PIXELLETTER_WAIVE_WITHDRAWAL_RIGHT	Renuncia al derecho de desistimiento de dos semanas para que los pedidos se ejecuten de inmediato; valor predeterminado true. false retrasa cada pedido dos semanas.
PIXELLETTER_DEFAULT_LOCATION	Centro de expedición predeterminado: 1 Múnich (DE), 2 Hausleiten cerca de Viena (AT), 3 Hamburgo (DE).
PIXELLETTER_DEFAULT_DESTINATION	País de destino predeterminado como código ISO de dos letras, por ejemplo DE.
PIXELLETTER_FORCE_TEST_MODE	Fuerza el modo de prueba para cada pedido; valor predeterminado false.
PIXELLETTER_TIMEOUT_MS	Tiempo de espera de la solicitud en milisegundos; valor predeterminado 120000.

Las credenciales solo se leen del entorno; no se almacena nada en el repositorio ni se escribe nada en el disco.

Herramientas

Herramienta	Propósito
send_letter	Envía documentos o texto plano como carta física, opcionalmente también como fax.
send_fax	Envía documentos o texto plano solo como fax.
get_account_info	Lee los datos de cliente almacenados y el crédito actual.
cancel_order	Cancela un pedido enviado mediante su identificador de pedido de PixelLetter.
sign_invoice	Envía documentos al servicio de firma electrónica de facturas y, opcionalmente, reenvía el PDF firmado por correo.
get_interface_reference	Consulta sin conexión de valores de acción, centros de expedición, códigos de servicio, límites y códigos de error.

send_letter

PDF ya preparado, el caso habitual:

{
  "testMode": true,
  "files": ["/Users/you/Documents/Briefe/2026-07-24-widerspruch.pdf"],
  "destination": "DE",
  "transaction": "widerspruch-4711"
}

Correo certificado con acuse de recibo, impreso en color a una sola cara:

{
  "testMode": false,
  "files": ["/Users/you/Documents/Briefe/kuendigung.pdf"],
  "destination": "DE",
  "registered": true,
  "returnReceipt": true,
  "colorPrint": true,
  "duplex": false
}

Texto plano, compuesto por PixelLetter, con la firma almacenada en la cuenta:

{
  "testMode": true,
  "address": ["Erika Mustermann", "Musterstr. 28", "81237 Musterstadt", "Deutschland"],
  "subject": "Ihre Anfrage vom 12.07.2026",
  "text": "Hallo Frau Mustermann,\n\nvielen Dank für Ihre Anfrage.\n\nMit freundlichen Grüßen\n\n%Unterschrift%\nMax Mustermann",
  "destination": "DE"
}

Reglas que la herramienta aplica antes de enviar nada:

• Un pedido lleva documentos o texto, no ambos. Varios documentos se convierten y fusionan en una sola carta, en el orden indicado.
• El país de destino es obligatorio para las cartas; un código incorrecto conlleva un franqueo incorrecto.
• La dirección del destinatario debe ser visible en el área de la ventanilla de la dirección del documento; PixelLetter lo comprueba antes del envío.
• Los tipos de carga permitidos son .pdf, .doc, .xls, .ppt, .rtf, .wpd, .psd, con un máximo de 50 MB. El error 053 muestra que PixelLetter puede restringir esto a PDF, por lo que PDF es la opción segura.
• Los servicios adicionales, la impresión en color y la impresión a doble cara son solo para cartas; un pedido de solo fax los rechaza. Los códigos 28 (acuse de recibo) y 29 (entrega en mano) requieren el 27 (certificado); el código 30 (certificado con depósito en buzón) es independiente. El correo certificado es un producto alemán; otros destinos generan el error 026.

Cada opción de la interfaz

Cobertura completa de los campos que documenta la interfaz. «Aplica a» indica qué tipo de envío acepta la opción; las combinaciones no válidas se rechazan antes de que salga la solicitud.

Campo de la API	Parámetro de la herramienta	Valores permitidos	Aplica a	Fuente
email	PIXELLETTER_EMAIL	correo de la cuenta	todos	Manual HTTPS
password	PIXELLETTER_PASSWORD	contraseña de la cuenta	todos	Manual HTTPS
agb	PIXELLETTER_ACCEPT_TERMS	ja, nein	todos	Manual HTTPS
widerrufsverzicht	PIXELLETTER_WAIVE_WITHDRAWAL_RIGHT	ja, nein, nein retrasa el pedido dos semanas	todos	Manual HTTPS
testmodus	testMode, PIXELLETTER_FORCE_TEST_MODE	true, false	todos	Manual HTTPS
order type	elegido de la entrada	text, upload, cancel	todos	Manual HTTPS, clase de referencia
action	send_letter, alsoSendFax, send_fax, sign_invoice	1 carta, 2 fax, 3 carta y fax, 4 firma de factura	todos	Manual HTTPS, manuales de firma
transaction	transaction	texto libre, devuelto con la respuesta	todos	Manual HTTPS
fax	faxNumber	formato internacional, +49 89 72448483	fax	Manual HTTPS
location	location	1 Múnich (DE), 2 Hausleiten cerca de Viena (AT), 3 Hamburgo (DE), valor predeterminado 1	carta, fax	Manual HTTPS
destination	destination, PIXELLETTER_DEFAULT_DESTINATION	código ISO de dos letras, obligatorio para cartas, ignorado para fax puro	carta	Manual HTTPS
addoption 27	registered	Einschreiben, correo certificado	carta	Manual HTTPS
addoption 28	returnReceipt	Rückschein, acuse de recibo, solo con 27	carta	Manual HTTPS
addoption 29	personalDelivery	Eigenhändig, entrega en mano, solo con 27	carta	Manual HTTPS
addoption 30	registeredDropIn	Einschreiben Einwurf, certificado con depósito en buzón, no combinable con 27, 28, 29	carta	Manual HTTPS
addoption 31	cashOnDelivery	Nachnahme, reembolso, se establece automáticamente cuando se proporciona el bloque de datos bancarios	carta	Clase de referencia 2.01
addoption 33	colorPrint	impresión en color en lugar de blanco y negro	carta	pyPostal, error 038
addoption 44	goGreen	GoGreen, franqueo neutro en CO2	carta	pyPostal
addoption otros	additionalServiceCodes	números brutos que PixelLetter acordó para tu cuenta	carta	Manual HTTPS
control	duplex	true doble cara (valor predeterminado de PixelLetter), false envía NODUPLEX para una sola cara	carta	pyPostal
control bruto	control	cualquier token que PixelLetter te haya dado, no combinable con duplex	carta, fax	Clase de referencia 2.01
returnaddress	returnAddress	valor bruto, sin significado publicado	carta, fax	Clase de referencia 2.01
wiretransfer/recipient/name	cashOnDelivery.name	de 1 a 27 caracteres	carta	Clase de referencia, errores 030 a 037
wiretransfer/recipient/bankaccountid	cashOnDelivery.bankAccountId	de 6 a 10 dígitos	carta	Clase de referencia, error 036
wiretransfer/recipient/blz	cashOnDelivery.bankCode	exactamente 8 dígitos	carta	Clase de referencia, error 037
wiretransfer/recipient/bankname	cashOnDelivery.bankName	de 1 a 27 caracteres	carta	Clase de referencia, error 031
wiretransfer/reasonforpayment1	cashOnDelivery.reasonForPayment1	hasta 27 caracteres	carta	Clase de referencia, error 032
wiretransfer/reasonforpayment2	cashOnDelivery.reasonForPayment2	hasta 27 caracteres	carta	Clase de referencia, error 033
wiretransfer/amount	cashOnDelivery.amount	XXXX,XX, de 3,00 a 1600,00 EUR	carta	Clase de referencia, errores 034, 035
text/address	address	líneas de dirección del destinatario, país incluido	carta, fax	Manual HTTPS
text/subject	subject	asunto de la carta	carta, fax	Manual HTTPS
text/message	text	texto plano, sin HTML, %Unterschrift% inserta la firma almacenada	carta, fax	Manual HTTPS
uploadfile0, uploadfile1, ...	files, inlineFiles	.pdf, .doc, .xls, .ppt, .rtf, .wpd, .psd, 50 MB cada uno	carta, fax, firma	Manual HTTPS
order type="cancel"/id	cancel_order.orderId	identificador de pedido de PixelLetter	cancelación	Clase de referencia 2.01
sender, recipient, cc, bcc, subject, body, filename	sign_invoice.notification.*	campos de correo electrónico de la notificación de firma	firma	Manuales de firma
info/account:info type="all"	get_account_info	sin parámetros	cuenta	Manual HTTPS

get_interface_reference devuelve la misma lista en tiempo de ejecución, incluida la tabla completa de códigos de error.

Lo que la interfaz no ofrece

Mencionado explícitamente, porque su ausencia es una propiedad de la API y no una omisión de este servidor:

• Sin lista de trabajos. No hay ninguna llamada documentada que liste o consulte pedidos enviados. cancel_order funciona con un identificador de pedido del correo de confirmación, get_account_info informa del saldo; todo lo demás vive en el área de cliente de PixelLetter.
• Sin formato de sobre ni de papel, sin clase de franqueo, sin velocidad de entrega, sin portada, sin sobre de respuesta, sin identificación del remitente. Estos no son campos de la interfaz. Las cartas van en un sobre con ventanilla DIN C6/5 y el franqueo depende del peso y del país de destino.
• Sin corrección de dirección. Premiumadress aparece en el error 088, pero debe configurarse por el soporte de PixelLetter para la cuenta y no tiene campo de solicitud.
• Postales, plantillas de carga y pedidos masivos. La clase de referencia y los códigos de error muestran que existen (font, número de plantilla, acción 5), pero ningún manual documenta sus valores de acción ni su estructura de campos. Enviar una acción adivinada podría producir un envío real e incorrecto, así que se han omitido.
• ref en el bloque de autenticación no tiene significado documentado y siempre se envía vacío, exactamente como hace la clase de referencia.

Verificación

npm test    # XML payloads, response parsing, option rules, configuration, HTTP layer with a mocked fetch

Las pruebas nunca tocan la API real. La capa HTTP se ejercita mediante un fetch inyectado, que comprueba el punto final, el campo xml, las partes uploadfileN, el indicador de modo de prueba y la asignación de códigos de error.

Licencia

MIT, ver LICENSE.