pixelletter-mcp

Local MCP server (stdio) for the PixelLetter HTTPS interface. Hand it a PDF and a destination country and PixelLetter prints, folds, franks and posts the letter, optionally as registered mail. It also sends faxes, cancels orders, reads the account balance and drives the electronic invoice signature.

It pairs with pdf-letter-mcp: that server writes a DIN 5008 letter PDF, this one puts it in the post. send_letter takes the absolute path that create_letter returns.

The implementation follows the published documentation: the HTTPS handbook, the e-mail handbook, the two signature handbooks, the reference PHP class (version 2.01) and the public error code list. Three values are not printed in those documents, colour printing, GoGreen postage and the NODUPLEX switch, and they are taken from the hudora/pyPostal client that has been sending real orders with them. They are marked as such in the table below. Nothing else is invented.

How the interface works

Everything is one multipart HTTPS POST to https://www.pixelletter.de/xml/index.php. The form field xml carries the order document, credentials included, and the fields uploadfile0, uploadfile1 and so on carry the documents. The answer is a small XML document: code 100 means the order was accepted, anything else is an error code from the published list. The final result, including whether the recipient address fitted the address window, arrives by e-mail a few hours later.

Test mode

Every sending tool needs an explicit testMode flag, there is no default. testMode: true runs the order exactly like a real one but PixelLetter never prints it, never sends it and never charges for it. testMode: false really posts the letter. Set PIXELLETTER_FORCE_TEST_MODE=true to pin the whole server to test mode while wiring things up.

Install

npm install
npm run build

Register the server in 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"

Or in ~/.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"
      }
    }
  }
}

Environment

Credentials are only read from the environment, nothing is stored in the repository and nothing is written to disk.

Tools

send_letter

Ready made PDF, the normal case:

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

Registered mail with return receipt, printed in colour on one side only:

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

Plain text, typeset by PixelLetter, with the signature stored in the account:

{
  "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"
}

Rules the tool enforces before anything is sent:

• One order carries either documents or text, not both. Several documents are converted and merged into one letter, in the order given.
• The destination country is mandatory for letters, a wrong code leads to wrong postage.
• The recipient address has to be visible in the address window area of the document, PixelLetter checks this before dispatch.
• Allowed upload types are .pdf, .doc, .xls, .ppt, .rtf, .wpd, .psd, 50 MB maximum. Error 053 shows that PixelLetter can restrict this to PDF, so PDF is the safe choice.
• Additional services, colour print and duplex are letter only, a pure fax order rejects them. Codes 28 (return receipt) and 29 (personal delivery) need 27 (registered), code 30 (drop-in registered) stands alone. Registered mail is a German product, other destinations run into error 026.

Every option of the interface

Full coverage of the fields the interface documents. "Applies to" says which dispatch type accepts the option, invalid combinations are rejected before the request goes out.