pixelletter-mcp

pixelletter-mcp

PixelLetter の HTTPS インターフェースを利用するローカル MCP サーバー（stdio）です。PDF と送付先の国を指定すると、PixelLetter がレターを印刷、折りたたみ、料金別納郵便の処理をして投函します。オプションで書留郵便にもできます。また、ファクスの送信、注文のキャンセル、アカウント残高の確認、電子インボイスへの署名にも対応しています。

pdf-letter-mcp と組み合わせて使用します。このサーバーが DIN 5008 に準拠したレターの PDF を作成し、こちらのサーバーが郵送します。send_letter には、create_letter が返す絶対パスを指定してください。

実装は、公開されているドキュメント、HTTPS ハンドブック、メールハンドブック、2 つの署名ハンドブック、リファレンス PHP クラス（バージョン 2.01）、公開エラーコード一覧に従っています。これらのドキュメントに記載されていない値が 3 つあります。カラー印刷、GoGreen 郵便、NODUPLEX スイッチです。実際の注文でこれらを使用している hudora/pyPostal クライアントから採用しました。該当する値には、以下の表でその旨を記載しています。それ以外に独自の値は追加していません。

インターフェースの仕組み

すべての処理は、https://www.pixelletter.de/xml/index.php への 1 回の multipart HTTPS POST で行います。フォームフィールド xml に認証情報を含む注文ドキュメントを指定し、uploadfile0、uploadfile1 などのフィールドにドキュメントを指定します。応答は小さな XML ドキュメントです。コード 100 は注文が受け付けられたことを示し、それ以外は公開されている一覧のエラーコードです。宛先の住所が封筒の宛名窓に収まったかどうかを含む最終結果は、数時間後にメールで届きます。

テストモード

送信を行う各ツールでは testMode フラグを明示的に指定する必要があります。デフォルト値はありません。testMode: true にすると、実際の注文とまったく同じように処理されますが、PixelLetter が印刷、送信、課金することはありません。testMode: false にすると、実際にレターを郵送します。設定作業中にサーバー全体をテストモードに固定するには、PIXELLETTER_FORCE_TEST_MODE=true を設定してください。

インストール

npm install
npm run build

サーバーを Claude Code に登録します。

claude mcp add pixelletter \
  --env [email protected] \
  --env PIXELLETTER_PASSWORD=your-password \
  -- node "/absolute/path/to/pixelletter-mcp/dist/src/index.js"

または、~/.claude.json / claude_desktop_config.json で設定します。

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

環境変数

変数	用途
PIXELLETTER_EMAIL	必須。PixelLetter アカウントの登録に使用したメールアドレスです。
PIXELLETTER_PASSWORD	必須。PixelLetter のパスワードです。
PIXELLETTER_ENDPOINT	インターフェースのエンドポイントです。デフォルトは https://www.pixelletter.de/xml/index.php です。
PIXELLETTER_ACCEPT_TERMS	各注文で PixelLetter の利用規約に同意します。デフォルトは true です。同意しないと API が注文を拒否します（エラー 013）。
PIXELLETTER_WAIVE_WITHDRAWAL_RIGHT	2 週間の撤回権を放棄し、注文をすぐに処理します。デフォルトは true です。false にすると、すべての注文が 2 週間遅延します。
PIXELLETTER_DEFAULT_LOCATION	デフォルトの発送拠点です。1 はミュンヘン（DE）、2 はウィーン近郊のハウスライテン（AT）、3 はハンブルク（DE）です。
PIXELLETTER_DEFAULT_DESTINATION	デフォルトの送付先の国を、2 文字の ISO コードで指定します。例：DE。
PIXELLETTER_FORCE_TEST_MODE	すべての注文をテストモードに固定します。デフォルトは false です。
PIXELLETTER_TIMEOUT_MS	リクエストのタイムアウト（ミリ秒）です。デフォルトは 120000 です。

認証情報は環境変数からのみ読み込まれます。リポジトリには保存されず、ディスクにも書き込まれません。

ツール

ツール	用途
send_letter	ドキュメントまたはプレーンテキストを実際のレターとして送信します。オプションでファクスも送信できます。
send_fax	ドキュメントまたはプレーンテキストをファクスとしてのみ送信します。
get_account_info	保存されている顧客情報と現在のクレジット残高を取得します。
cancel_order	PixelLetter の注文 ID を指定して、送信済みの注文をキャンセルします。
sign_invoice	電子インボイス署名サービスにドキュメントを送信し、オプションで署名済み PDF をメールで転送します。
get_interface_reference	アクション値、発送拠点、サービスコード、上限、エラーコードをオフラインで参照します。

send_letter

完成済みのPDFの場合（通常のケース）：

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

受領通知付きの書留郵便で、片面のみカラー印刷する場合：

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

アカウントに保存された署名を使い、PixelLetterで組版したプレーンテキストの場合：

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

送信前にツールが適用するルール：

• 1件の注文には、書類かテキストのどちらか一方を指定します。両方は指定できません。複数の書類は変換され、指定された順序で1通の手紙にまとめられます。
• 手紙には宛先の国が必須です。コードを間違えると、郵便料金も間違います。
• 書類の住所表示窓の位置に受取人の住所が見えている必要があります。PixelLetterは発送前にこれを確認します。
• アップロードできるファイル形式は.pdf、.doc、.xls、.ppt、.rtf、.wpd、.psdで、最大サイズは50 MBです。エラー053は、PixelLetterがPDFのみに制限できることを示しています。そのため、PDFが確実な選択肢です。
• 追加サービス、カラー印刷、両面印刷を指定できるのは手紙のみです。FAXのみの注文ではこれらは拒否されます。コード28（受領通知）と29（本人への手渡し）にはコード27（書留）が必要です。コード30（投函式書留）は単独で指定できます。書留郵便はドイツ国内向けのサービスのため、その他の宛先ではエラー026が発生します。

インターフェースのすべてのオプション

インターフェースに記載されているフィールドをすべて網羅しています。「適用対象」は、どの発送タイプでそのオプションを使用できるかを示します。無効な組み合わせは、リクエストの送信前に拒否されます。

API フィールド	ツールのパラメーター	許可される値	対象	出典
email	PIXELLETTER_EMAIL	アカウントのメールアドレス	すべて	HTTPS ハンドブック
password	PIXELLETTER_PASSWORD	アカウントのパスワード	すべて	HTTPS ハンドブック
agb	PIXELLETTER_ACCEPT_TERMS	ja、nein	すべて	HTTPS ハンドブック
widerrufsverzicht	PIXELLETTER_WAIVE_WITHDRAWAL_RIGHT	ja、nein、nein の場合、注文は2週間遅れます	すべて	HTTPS ハンドブック
testmodus	testMode、PIXELLETTER_FORCE_TEST_MODE	true、false	すべて	HTTPS ハンドブック
order type	入力内容から選択	text、upload、cancel	すべて	HTTPS ハンドブック、リファレンスクラス
action	send_letter、alsoSendFax、send_fax、sign_invoice	1 レター、2 ファクス、3 レターとファクス、4 請求書への署名	すべて	HTTPS ハンドブック、署名ハンドブック
transaction	transaction	任意のテキスト。応答とともに返されます	すべて	HTTPS ハンドブック
fax	faxNumber	国際形式、+49 89 72448483	ファクス	HTTPS ハンドブック
location	location	1 ミュンヘン（DE）、2 ウィーン近郊のハウスライテン（AT）、3 ハンブルク（DE）、デフォルトは 1	レター、ファクス	HTTPS ハンドブック
destination	destination、PIXELLETTER_DEFAULT_DESTINATION	2文字の ISO コード。レターでは必須、ファクスのみの場合は無視されます	レター	HTTPS ハンドブック
addoption 27	registered	Einschreiben、書留郵便	レター	HTTPS ハンドブック
addoption 28	returnReceipt	Rückschein、配達証明。27と併用する場合のみ	レター	HTTPS ハンドブック
addoption 29	personalDelivery	Eigenhändig、本人限定受取。27と併用する場合のみ	レター	HTTPS ハンドブック
addoption 30	registeredDropIn	Einschreiben Einwurf、投函記録付き書留。27、28、29とは併用できません	レター	HTTPS ハンドブック
addoption 31	cashOnDelivery	Nachnahme、銀行口座情報ブロックが指定されると自動設定されます	レター	リファレンスクラス 2.01
addoption 33	colorPrint	白黒印刷の代わりにカラー印刷	レター	pyPostal、エラー 038
addoption 44	goGreen	GoGreen、CO2 ニュートラルな郵送	レター	pyPostal
その他の addoption	additionalServiceCodes	PixelLetter がアカウント用に合意した数値をそのまま指定	レター	HTTPS ハンドブック
control	duplex	true は両面（PixelLetter のデフォルト）、false は片面印刷用に NODUPLEX を送信	レター	pyPostal
control 生値	control	PixelLetter から提供された任意のトークン。duplex とは併用できません	レター、ファクス	リファレンスクラス 2.01
returnaddress	returnAddress	生の値。公表されている意味はありません	レター、ファクス	リファレンスクラス 2.01
wiretransfer/recipient/name	cashOnDelivery.name	1～27文字	レター	リファレンスクラス、エラー 030～037
wiretransfer/recipient/bankaccountid	cashOnDelivery.bankAccountId	6～10桁	レター	リファレンスクラス、エラー 036
wiretransfer/recipient/blz	cashOnDelivery.bankCode	ちょうど8桁	レター	リファレンスクラス、エラー 037
wiretransfer/recipient/bankname	cashOnDelivery.bankName	1～27文字	レター	リファレンスクラス、エラー 031
wiretransfer/reasonforpayment1	cashOnDelivery.reasonForPayment1	最大27文字	レター	リファレンスクラス、エラー 032
wiretransfer/reasonforpayment2	cashOnDelivery.reasonForPayment2	最大27文字	レター	リファレンスクラス、エラー 033
wiretransfer/amount	cashOnDelivery.amount	XXXX,XX、3,00～1600,00 EUR	レター	リファレンスクラス、エラー 034、035
text/address	address	宛先住所の各行。国を含みます	レター、ファクス	HTTPS ハンドブック
text/subject	subject	レターの件名	レター、ファクス	HTTPS ハンドブック
text/message	text	プレーンテキスト。HTML は不可。%Unterschrift% で保存済みの署名を挿入します	レター、ファクス	HTTPS ハンドブック
uploadfile0、uploadfile1、...	files、inlineFiles	.pdf、.doc、.xls、.ppt、.rtf、.wpd、.psd、各50 MB	レター、ファクス、署名	HTTPS ハンドブック
order type="cancel"/id	cancel_order.orderId	PixelLetter の注文 ID	キャンセル	リファレンスクラス 2.01
sender、recipient、cc、bcc、subject、body、filename	sign_invoice.notification.*	署名通知のメールフィールド	署名	署名ハンドブック
info/account:info type="all"	get_account_info	パラメーターなし	アカウント	HTTPS ハンドブック
get_interface_reference は、エラーコード表全体を含む同じリストを実行時に返します。

インターフェースで提供されない機能

これらが明記されているのは、サーバーの不備ではなく、API の仕様として提供されていないためです。

• ジョブ一覧はありません。 送信済みの注文を一覧表示したり、照会したりするドキュメント化された呼び出しはありません。cancel_order は確認メールに記載された注文 ID を使用し、get_account_info は残高を報告します。それ以外の情報はすべて PixelLetter の顧客エリアで確認できます。
• 封筒や用紙の形式、郵便料金の区分、配達速度、表紙、返信用封筒、差出人の識別機能はありません。 これらに対応するフィールドはインターフェースにありません。レターは DIN C6/5 の窓付き封筒に封入され、郵便料金は重量と宛先の国に応じて決まります。
• 住所の修正機能はありません。 エラー 088 には Premiumadress が記載されていますが、アカウントで利用するには PixelLetter のサポートによる設定が必要で、リクエスト用のフィールドもありません。
• ポストカード、アップロード用テンプレート、一括注文には対応していません。 リファレンスクラスとエラーコードから、これらの機能が存在することはわかります（font、テンプレート番号、アクション 5）。しかし、ハンドブックにはアクション値やフィールド構成が記載されていません。推測したアクションを送信すると、実際に誤った発送が行われる可能性があるため、対象外としています。
• 認証ブロックの ref は、ドキュメントに意味が記載されておらず、リファレンスクラスと同様に常に空で送信されます。

検証

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

テストで実際の API にアクセスすることはありません。注入された fetch を通じて HTTP レイヤーをテストし、エンドポイント、xml フィールド、uploadfileN パーツ、テストモードフラグ、エラーコードのマッピングを確認します。

ライセンス

MIT です。詳細は LICENSE を参照してください。