PixelLetter MCP

pixelletter-mcp

Servidor MCP local (stdio) para a interface HTTPS do PixelLetter. Entregue um PDF e um país de destino e a PixelLetter imprime, dobra, sela e posta a carta, opcionalmente como registro. Também envia faxes, cancela pedidos, lê o saldo da conta e aciona a assinatura eletrônica de faturas.

Ele se integra ao pdf-letter-mcp: esse servidor gera um PDF de carta no padrão DIN 5008, este o coloca no correio. send_letter recebe o caminho absoluto que create_letter retorna.

A implementação segue a documentação publicada: o manual HTTPS, o manual de e-mail, os dois manuais de assinatura, a classe PHP de referência (versão 2.01) e a lista pública de códigos de erro. Três valores não estão impressos nesses documentos — impressão colorida, postagem GoGreen e o interruptor NODUPLEX — e foram retirados do cliente hudora/pyPostal, que já envia pedidos reais com eles. Eles estão marcados como tal na tabela abaixo. Nada mais foi inventado.

Como a interface funciona

Tudo é um único POST HTTPS multipart para https://www.pixelletter.de/xml/index.php. O campo de formulário xml carrega o documento do pedido, incluindo credenciais, e os campos uploadfile0, uploadfile1 e assim por diante carregam os documentos. A resposta é um pequeno documento XML: o código 100 significa que o pedido foi aceito, qualquer outra coisa é um código de erro da lista publicada. O resultado final, incluindo se o endereço do destinatário coube na janela do envelope, chega por e-mail algumas horas depois.

Modo de teste

Cada ferramenta de envio precisa de um sinalizador explícito testMode, não há padrão. testMode: true executa o pedido exatamente como um real, mas a PixelLetter nunca imprime, nunca envia e nunca cobra por ele. testMode: false realmente posta a carta. Defina PIXELLETTER_FORCE_TEST_MODE=true para fixar o servidor inteiro em modo de teste enquanto configura as conexões.

Instalação

npm install
npm run build

Registre o servidor no 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"

Ou no ~/.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"
      }
    }
  }
}

Ambiente

Variável	Finalidade
PIXELLETTER_EMAIL	Obrigatória. O endereço de e-mail com o qual a conta PixelLetter está registrada.
PIXELLETTER_PASSWORD	Obrigatória. A senha da PixelLetter.
PIXELLETTER_ENDPOINT	Endpoint da interface. Padrão https://www.pixelletter.de/xml/index.php.
PIXELLETTER_ACCEPT_TERMS	Aceita os termos da PixelLetter em cada pedido, padrão true. A API rejeita pedidos caso contrário (erro 013).
PIXELLETTER_WAIVE_WITHDRAWAL_RIGHT	Abre mão do direito de arrependimento de duas semanas para que os pedidos sejam executados imediatamente, padrão true. false atrasa cada pedido em duas semanas.
PIXELLETTER_DEFAULT_LOCATION	Centro de despacho padrão: 1 Munique (DE), 2 Hausleiten perto de Viena (AT), 3 Hamburgo (DE).
PIXELLETTER_DEFAULT_DESTINATION	País de destino padrão como código ISO de duas letras, por exemplo DE.
PIXELLETTER_FORCE_TEST_MODE	Força o modo de teste em cada pedido, padrão false.
PIXELLETTER_TIMEOUT_MS	Tempo limite de solicitação em milissegundos, padrão 120000.

As credenciais são lidas apenas do ambiente, nada é armazenado no repositório e nada é gravado em disco.

Ferramentas

Ferramenta	Finalidade
send_letter	Envia documentos ou texto simples como carta física, opcionalmente também como fax.
send_fax	Envia documentos ou texto simples apenas como fax.
get_account_info	Lê os dados do cliente armazenados e o crédito atual.
cancel_order	Cancela um pedido enviado pelo ID do pedido PixelLetter.
sign_invoice	Envia documentos ao serviço de assinatura eletrônica de faturas e opcionalmente envia o PDF assinado por e-mail.
get_interface_reference	Consulta offline de valores de ação, centros de despacho, códigos de serviço, limites e códigos de erro.

send_letter

PDF pronto, o caso normal:

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

Registro com aviso de recebimento, impresso em cores em um único lado:

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

Texto simples, formatado pela PixelLetter, com a assinatura armazenada na conta:

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

Regras que a ferramenta aplica antes de enviar qualquer coisa:

• Um pedido carrega documentos ou texto, não ambos. Vários documentos são convertidos e mesclados em uma única carta, na ordem fornecida.
• O país de destino é obrigatório para cartas; um código errado leva a postagem incorreta.
• O endereço do destinatário precisa estar visível na área da janela do envelope do documento; a PixelLetter verifica isso antes do envio.
• Tipos de upload permitidos são .pdf, .doc, .xls, .ppt, .rtf, .wpd, .psd, máximo de 50 MB. O erro 053 mostra que a PixelLetter pode restringir isso a PDF, então PDF é a escolha segura.
• Serviços adicionais, impressão colorida e frente e verso são apenas para cartas; um pedido de fax puro os rejeita. Os códigos 28 (aviso de recebimento) e 29 (entrega pessoal) precisam do 27 (registrado), o código 30 (registro em caixa de correio) é independente. Registro é um produto alemão; outros destinos resultam no erro 026.

Cada opção da interface

Cobertura completa dos campos que a interface documenta. "Aplica-se a" indica qual tipo de despacho aceita a opção; combinações inválidas são rejeitadas antes de a solicitação sair.

Campo da API	Parâmetro da ferramenta	Valores permitidos	Aplica-se a	Fonte
email	PIXELLETTER_EMAIL	e-mail da conta	todos	manual HTTPS
password	PIXELLETTER_PASSWORD	senha da conta	todos	manual HTTPS
agb	PIXELLETTER_ACCEPT_TERMS	ja, nein	todos	manual HTTPS
widerrufsverzicht	PIXELLETTER_WAIVE_WITHDRAWAL_RIGHT	ja, nein, nein atrasa o pedido em duas semanas	todos	manual HTTPS
testmodus	testMode, PIXELLETTER_FORCE_TEST_MODE	true, false	todos	manual HTTPS
order type	escolhido da entrada	text, upload, cancel	todos	manual HTTPS, classe de referência
action	send_letter, alsoSendFax, send_fax, sign_invoice	1 carta, 2 fax, 3 carta e fax, 4 assinatura de fatura	todos	manual HTTPS, manuais de assinatura
transaction	transaction	texto livre, retornado com a resposta	todos	manual HTTPS
fax	faxNumber	formato internacional, +49 89 72448483	fax	manual HTTPS
location	location	1 Munique (DE), 2 Hausleiten perto de Viena (AT), 3 Hamburgo (DE), padrão 1	carta, fax	manual HTTPS
destination	destination, PIXELLETTER_DEFAULT_DESTINATION	código ISO de duas letras, obrigatório para cartas, ignorado para fax puro	carta	manual HTTPS
addoption 27	registered	Einschreiben, registro	carta	manual HTTPS
addoption 28	returnReceipt	Rückschein, aviso de recebimento, apenas com 27	carta	manual HTTPS
addoption 29	personalDelivery	Eigenhändig, entrega pessoal, apenas com 27	carta	manual HTTPS
addoption 30	registeredDropIn	Einschreiben Einwurf, registro em caixa de correio, não combinável com 27, 28, 29	carta	manual HTTPS
addoption 31	cashOnDelivery	Nachnahme, definido automaticamente quando o bloco de dados bancários é fornecido	carta	classe de referência 2.01
addoption 33	colorPrint	impressão colorida em vez de preto e branco	carta	pyPostal, erro 038
addoption 44	goGreen	GoGreen, postagem neutra em CO2	carta	pyPostal
addoption outros	additionalServiceCodes	números brutos que a PixelLetter acordou para sua conta	carta	manual HTTPS
control	duplex	true frente e verso (padrão da PixelLetter), false envia NODUPLEX para um único lado	carta	pyPostal
control bruto	control	qualquer token que a PixelLetter lhe deu, não pode ser combinado com duplex	carta, fax	classe de referência 2.01
returnaddress	returnAddress	valor bruto, sem significado publicado	carta, fax	classe de referência 2.01
wiretransfer/recipient/name	cashOnDelivery.name	1 a 27 caracteres	carta	classe de referência, erros 030 a 037
wiretransfer/recipient/bankaccountid	cashOnDelivery.bankAccountId	6 a 10 dígitos	carta	classe de referência, erro 036
wiretransfer/recipient/blz	cashOnDelivery.bankCode	exatamente 8 dígitos	carta	classe de referência, erro 037
wiretransfer/recipient/bankname	cashOnDelivery.bankName	1 a 27 caracteres	carta	classe de referência, erro 031
wiretransfer/reasonforpayment1	cashOnDelivery.reasonForPayment1	até 27 caracteres	carta	classe de referência, erro 032
wiretransfer/reasonforpayment2	cashOnDelivery.reasonForPayment2	até 27 caracteres	carta	classe de referência, erro 033
wiretransfer/amount	cashOnDelivery.amount	XXXX,XX, 3,00 a 1600,00 EUR	carta	classe de referência, erros 034, 035
text/address	address	linhas do endereço do destinatário, país incluído	carta, fax	manual HTTPS
text/subject	subject	assunto da carta	carta, fax	manual HTTPS
text/message	text	texto simples, sem HTML, %Unterschrift% insere a assinatura armazenada	carta, fax	manual HTTPS
uploadfile0, uploadfile1, ...	files, inlineFiles	.pdf, .doc, .xls, .ppt, .rtf, .wpd, .psd, 50 MB cada	carta, fax, assinatura	manual HTTPS
order type="cancel"/id	cancel_order.orderId	ID do pedido PixelLetter	cancelamento	classe de referência 2.01
sender, recipient, cc, bcc, subject, body, filename	sign_invoice.notification.*	campos de e-mail da notificação de assinatura	assinatura	manuais de assinatura
info/account:info type="all"	get_account_info	sem parâmetros	conta	manual HTTPS

get_interface_reference retorna a mesma lista em tempo de execução, incluindo a tabela completa de códigos de erro.

O que a interface não oferece

Nomeado explicitamente, porque sua ausência é uma propriedade da API e não uma omissão deste servidor:

• Sem lista de trabalhos. Não há chamada documentada que liste ou consulte pedidos enviados. cancel_order funciona com um ID de pedido do e-mail de confirmação, get_account_info informa o saldo, todo o resto vive na área do cliente PixelLetter.
• Sem formato de envelope ou papel, sem classe de postagem, sem velocidade de entrega, sem folha de rosto, sem envelope de resposta, sem identificação do remetente. Esses não são campos da interface. Cartas vão em um envelope de janela DIN C6/5 e a postagem segue peso e país de destino.
• Sem correção de endereço. Premiumadress aparece no erro 088, mas precisa ser configurado pelo suporte da PixelLetter para a conta e não tem campo de solicitação.
• Cartões postais, modelos de upload e pedidos em massa. A classe de referência e os códigos de erro mostram que existem (font, número do modelo, ação 5), mas nenhum manual documenta seus valores de ação ou layout de campos. Enviar uma ação adivinhada poderia produzir um despacho real e errado, então foram deixados de fora.
• ref no bloco de autenticação não tem significado documentado e é sempre enviado vazio, exatamente como a classe de referência faz.

Verificação

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

Os testes nunca tocam a API ao vivo. A camada HTTP é exercitada por meio de um fetch injetado, que verifica o endpoint, o campo xml, as partes uploadfileN, o sinalizador de modo de teste e o mapeamento de códigos de erro.

Licença

MIT, veja LICENSE.