pixelletter-mcp

pixelletter-mcp

面向 PixelLetter HTTPS 接口的本地 MCP 服务（stdio）。提供 PDF 和目的地国家后，PixelLetter 会打印、折叠、贴邮资并寄出信件，也可选择使用挂号邮件。它还可发送传真、取消订单、读取账户余额并处理电子发票签名。

它与 pdf-letter-mcp 配合使用：该服务会生成 DIN 5008 信件 PDF，本服务则负责将其寄出。send_letter 接受 create_letter 返回的绝对路径。

本实现遵循已发布的文档：HTTPS 手册、电子邮件手册、两份签名手册、参考 PHP 类（版本 2.01）以及公开错误代码列表。其中有三个值未在这些文档中列出：彩色打印、GoGreen 邮资和 NODUPLEX 开关。这些值取自 hudora/pyPostal 客户端，该客户端一直使用这些值发送真实订单。下表中已对此作出标注。除此之外，没有任何内容是凭空编造的。

接口工作方式

所有操作都会通过一个 multipart HTTPS POST 请求发送到 https://www.pixelletter.de/xml/index.php。表单字段 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	放弃两周撤销权，以便立即处理订单，默认为 true。设为 false 时，每笔订单都会延迟两周。
PIXELLETTER_DEFAULT_LOCATION	默认寄件中心：1 慕尼黑（DE）、2 维也纳附近的 Hausleiten（AT）、3 汉堡（DE）。
PIXELLETTER_DEFAULT_DESTINATION	默认目的地国家，两字母 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"
}

发送前工具会执行以下规则：

• 一个订单只能包含文档或文本，不能两者兼有。多个文档会按给定顺序转换并合并为一封信。
• 信件必须指定目的地国家，代码错误会导致邮资错误。
• 收件人地址必须显示在文档的信封窗口区域内，PixelLetter 会在寄出前检查这一点。
• 允许上传的文件类型为 .pdf、.doc、.xls、.ppt、.rtf、.wpd、.psd，最大 50 MB。错误 053 表明 PixelLetter 可以将此限制为 PDF，因此 PDF 是稳妥的选择。
• 附加服务、彩色打印和双面打印仅适用于信件，纯传真订单不接受这些选项。代码 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 会将订单延迟两周	全部	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 维也纳附近的 Hausleiten（AT）、3 汉堡（DE），默认值为 1	信件、传真	HTTPS 手册
destination	destination、PIXELLETTER_DEFAULT_DESTINATION	两字母 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。HTTP 层通过注入的 fetch 进行测试，以检查端点、xml 字段、uploadfileN 部分、测试模式标记和错误代码映射。

许可证

MIT，参见 LICENSE。