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.

`get_interface_reference` returns the same list at runtime, including the full error code table.

What the interface does not offer

Named explicitly, because their absence is a property of the API and not an omission of this server:

• No job list. There is no documented call that lists or queries submitted orders. `cancel_order` works on an order id from the confirmation e-mail, `get_account_info` reports the balance, everything else lives in the PixelLetter customer area.
• No envelope or paper format, no postage class, no delivery speed, no cover sheet, no reply envelope, no sender identification. These are no fields of the interface. Letters go into a DIN C6/5 window envelope and the postage follows weight and destination country.
• No address correction. Premiumadress shows up in error 088, but it has to be set up by PixelLetter support for the account and has no request field.
• Postcards, upload templates and bulk orders. The reference class and the error codes show they exist (`font`, template number, action 5), but no handbook documents their action values or their field layout. Sending a guessed action could produce a real, wrong dispatch, so they are left out.
• `ref` in the auth block has no documented meaning and is always sent empty, exactly like the reference class does.

Verification

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

The tests never touch the live API. The HTTP layer is exercised through an injected `fetch`, which checks the endpoint, the `xml` field, the `uploadfileN` parts, the test mode flag and the error code mapping.

License

MIT, see LICENSE.