postals-mcp

Postals

让任何 AI 都能化身直邮机器的 Agent 技能。 调用一次工具，即可寄出真正的手写明信片。由 USPS 投递。

通过任何兼容 MCP 的 AI Agent 寄送实体手写明信片——Claude Desktop、Cursor、Claude Code、OpenClaw、n8n、LangChain、CrewAI，或你自己的代码。Postals 负责图片上传、卡片创建、机器人手写（使用真实笔和墨水）以及 USPS 邮寄。

网站：postals.ai

• 💌 每张卡片 $4.99——无需订阅，没有月度最低消费
• ✍️ 真实手写——机器人钢笔使用真实墨水（不是字体模拟）
• 📬 3–5 个工作日——打印后通过 USPS 邮寄
• 🤖 专为 Agent 打造——一次工具调用、支出控制、幂等性、测试模式
• 🌎 美国及国际地区——全球投递，价格因目的地而异

---

目录

• 为何推出此项目
• 快速开始（不到 5 分钟）
• 客户端配置
• 工具参考
• 泳池建造商工作流
• 消息生成
• 图片处理
• 测试模式
• 支出控制
• 错误处理
• 配置参考
• 手写风格
• 故障排除
• 常见问题
• 后续计划（路线图）
• 贡献
• 许可证

---

为何推出此项目

AI Agent 生态系统中正在兴起一种新模式：自主机器人扫描世界（卫星图像、社交媒体、公共记录），识别商机，并通过真实的实体邮件联系潜在客户。泳池建造商、景观设计师、屋顶施工人员、太阳能安装商、房地产经纪人——他们正通过机器人寄出的明信片，谈成价值五位数和六位数的交易。

Postals 出现之前，每个建造商都要手工搭建自己的邮寄流程：图片上传、卡片模板、打印 API、地址验证、交给 USPS 投递、追踪。整个过程耗时数周，而且很脆弱。

我们将这一切封装成一个工具。你的 Agent 只需调用 send_postcard，提供收件人和消息。其余工作由我们完成。

---

快速开始

1. 注册并获取 API 密钥

即将推出——开发者门户 postals.ai/developers 即将上线。 上线后，流程如下：

1. 前往 postals.ai/developers
2. 使用邮箱创建账户（一键魔法链接——无需密码）
3. 为钱包充值（通过 Stripe 或加密货币充值 $25 / $50 / $100 / $250）
4. 复制你的 postals_live_ API 密钥
5. 将其粘贴到 MCP 配置中（见下方第 2 步）

就这么简单。无需外部账户，只需 Postals。

2. 将服务添加到 MCP 客户端

选项 A——让你的编码 Agent 帮你安装（最快方式）

如果你使用的是 Claude Code、Cursor、Continue、Aider，或任何可以访问文件系统的 MCP 客户端，只需告诉你的 Agent：

为此客户端安装 postals-mcp MCP 服务。我的 Postals API 密钥是：PASTE_YOUR_KEY_HERE。请先启用测试模式，以便我在寄出真实卡片前验证设置。

你的 Agent 会找到 MCP 配置文件，将 postals 条目合并到现有的 mcpServers 中（保留已有的其他服务），配置好环境变量，并提示你重启客户端。你无需接触 JSON。

可选——在同一条提示中添加回邮地址详情，这样调用 send_postcard 时就无需每次单独指定：

……并使用 Jane Smith、123 Main St、Austin TX 78701 作为我的回邮地址。

然后完全退出并重新启动客户端（macOS 上按 Cmd+Q——只关闭窗口还不够）。

选项 B — 直接编辑 MCP 配置文件

对于Claude Desktop（默认没有内置文件系统访问权限），或任何希望手动设置的客户端，请编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "postals": {
      "command": "npx",
      "args": ["-y", "postals-mcp"],
      "env": {
        "POSTALS_API_KEY": "your_api_key",
        "POSTALS_SENDER_NAME": "Jane Smith",
        "POSTALS_SENDER_ADDRESS": "123 Main St",
        "POSTALS_SENDER_CITY": "Austin",
        "POSTALS_SENDER_STATE": "TX",
        "POSTALS_SENDER_ZIP": "78701",
        "POSTALS_TEST_MODE": "true"
      }
    }
  }
}

其他客户端（Cursor、Claude Code、OpenClaw）的配置请见下方的客户端配置部分。

编辑后，请完全重启客户端。（不只是关闭窗口，而是从菜单中退出。）

3. 验证是否正常工作

打开新聊天并询问：

“列出可用的 MCP 工具。”

你应该会看到 send_postcard 和 generate_message。

4. 发送测试卡片

仍处于测试模式（POSTALS_TEST_MODE=true）时，询问：

“给 Jane Smith 寄一张明信片，地址是 123 Oak St, Austin TX 78701，内容写‘感谢昨天精彩的会议——期待后续合作。’”

Agent 会调用 send_postcard。你会收到一个模拟的 order_id，并确认测试模式已开启。不会寄出卡片，也不会产生费用。

5. 正式启用

从配置中移除 POSTALS_TEST_MODE（或将其设为 false），重启客户端，之后发送的卡片就会实际寄出。

---

客户端配置

这里提供适用于所有主流 MCP 客户端的即用型配置。如果你使用 Claude Code、Cursor、Continue 或 Aider，可以完全跳过本部分——只需让 Agent 安装 Postals（请参见快速入门中的选项 A），它会为你处理配置。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "postals": {
      "command": "npx",
      "args": ["-y", "postals-mcp"],
      "env": {
        "POSTALS_API_KEY": "your_key"
      }
    }
  }
}

Cursor

全局：~/.cursor/mcp.json 每个项目：仓库根目录中的 .cursor/mcp.json

{
  "mcpServers": {
    "postals": {
      "command": "npx",
      "args": ["-y", "postals-mcp"],
      "env": {
        "POSTALS_API_KEY": "your_key"
      }
    }
  }
}

Claude Code

claude mcp add postals npx -y postals-mcp

然后在 ~/.claude/settings.json 的 mcpServers.postals.env 下设置环境变量。

OpenClaw / InstaClaw

完整的、面向 Agent 的技能定义请参见随附的 SKILL.md。如需独立使用 OpenClaw：

mcp_servers:
  postals:
    command: npx
    args: ["-y", "postals-mcp"]
    env:
      POSTALS_API_KEY: ${POSTALS_API_KEY}

n8n（通过 Composio — v1.1+）

从 Composio 市场安装 Postals 工具包。可一键添加到任何工作流。相关文档发布后，请参见 Composio 文档。

自定义 Agent（编程方式）

任何 MCP 客户端库都可以使用。以下是使用官方 TypeScript SDK 的示例：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "postals-mcp"],
  env: { POSTALS_API_KEY: "your_key", POSTALS_TEST_MODE: "true" },
});
const client = new Client({ name: "my-agent", version: "1.0" }, { capabilities: {} });
await client.connect(transport);

const result = await client.callTool({
  name: "send_postcard",
  arguments: {
    to_name: "John Smith",
    to_address: "123 Oak St",
    to_city: "Austin",
    to_state: "TX",
    to_zip: "78701",
    message: "Hey John — thought you'd love this.",
    front_image_url: "https://example.com/render.png",
    idempotency_key: "john-smith-123-oak-001",
  },
});

---

工具参考

send_postcard

向美国地址邮寄一张实体手写明信片。

输入

字段	类型	必填	说明
to_name	字符串	✓	收件人全名
to_address	字符串	✓	街道地址第 1 行
to_address_2	字符串		公寓／套房／单元号
to_city	字符串	✓	城市
to_state	字符串	✓	两位字母的美国州代码
to_zip	字符串	✓	5 位 ZIP 邮编（或 5+4 位）
message	字符串	✓	手写内容（最多 400 个字符）
front_image_url	字符串		明信片正面图片的 HTTPS URL（PNG/JPEG）。默认使用 POSTALS_DEFAULT_CARD_IMAGE。
handwriting_style	字符串		字体名称。默认值：Joyful Jennifer
return_address	对象		本次调用的寄件人地址覆盖值。默认使用 POSTALS_SENDER_* 环境变量。
idempotency_key	字符串		唯一去重键。相同的键会返回相同结果，不会重复寄送。有效期为 24 小时。

输出（成功）

{
  "success": true,
  "order_id": 196937,
  "card_id": 305570,
  "recipient": "John Smith",
  "estimated_delivery": "3-5 business days via USPS",
  "balance_remaining": -1,
  "cards_available": -1,
  "cards_sent_today": 7,
  "daily_limit": 25
}

使用来自 postals.ai/developers 的 postals_live_ API 密钥时，balance_remaining 和 cards_available 会返回实际值。

**输出（测试模式）**会额外包含 test_mode: true 和 mock_order_id。不会寄出卡片。

**输出（错误）**会返回 isError: true 及可据此采取操作的消息。请参见错误处理。

generate_message

由 AI 起草个性化明信片内容。若已配置 Cloudflare AI，则使用它；否则返回结构化提示词，供你的 Agent 自行生成（通常效果也一样好，因为 Agent 本身已经是大模型）。

输入

字段	类型	必填	描述
recipient_context	字符串	✓	收件人是谁，以及你写信的原因
tone	枚举		warm（默认）、professional、casual、excited
max_chars	数字		消息的最大长度。默认 350，最大 400。
sender_context	字符串		发件人是谁

输出（已配置 AI）

{
  "message": "Hey John — drove by your place on Oak St and couldn't help but picture how a pool would transform that backyard. Happy to share a quick render if you're curious. — Kevin, Blue Wave Pools",
  "char_count": 212,
  "tone": "warm",
  "ai_generated": true
}

输出（未配置 AI） — 返回系统提示词和用户提示词，供你的 Agent 输入自己的大模型：

{
  "message": null,
  "ai_generated": false,
  "prompt": {
    "system": "You write short, personal messages for physical handwritten postcards...",
    "user": "Recipient: John Smith, homeowner at 123 Oak St...\nSender: Blue Wave Pools\n\nWrite the postcard message now."
  },
  "instructions": "Cloudflare AI not configured. Use the system/user prompts above to generate the message...",
  "tone": "warm",
  "max_chars": 350
}

compose_postcard_message（MCP 提示词）

一种 MCP 提示词原语（不是工具）。返回格式化的提示词模板，供你的 Agent 配合自己的大模型使用。无需依赖任何外部 API。适用于需要确定性、无依赖的消息撰写场景。

参数： recipient、sender（可选）、tone（可选）。

---

泳池建造商工作流

这是让自主明信片寄送声名鹊起的爆款用例。泳池建造商会运行 Agent，执行以下操作：

1. 扫描社区的卫星图像（Google Maps、Nearmap 等）
2. 分类——找出没有泳池的房屋
3. 渲染——生成个性化的改造前后对比图，展示在对应后院安装泳池的效果
4. 撰写——针对该房屋写一段亲切且具体的消息
5. 寄送——邮寄手写明信片
6. 成交——每周都有五位数金额的订单成交

Postals 通过两次工具调用负责步骤 4–5。步骤 1–3 由你负责（任何图像流水线都可以）。

完整示例

// Your pipeline produced:
//   - homeowner: { name, street, city, state, zip }
//   - renderUrl: "https://cdn.mybucket.com/renders/123-oak-st-pool.jpg"

const msg = await generate_message({
  recipient_context: `${homeowner.name}, homeowner at ${homeowner.street}. Corner lot with large flat backyard, no pool.`,
  sender_context: "Blue Wave Pools — Austin, TX. Specializing in fiberglass pools installed in 14 days.",
  tone: "warm",
});

const result = await send_postcard({
  to_name: homeowner.name,
  to_address: homeowner.street,
  to_city: homeowner.city,
  to_state: homeowner.state,
  to_zip: homeowner.zip,
  message: msg.message,
  front_image_url: renderUrl,
  idempotency_key: `prospect-${homeowner.id}`,  // crucial for retries
});

console.log(`Mailed card ${result.order_id}. ${result.cards_sent_today}/${result.daily_limit} today.`);

为什么有效

• 真实手写字迹的打开率比印刷邮件高 5–10 倍
• 高度个性化的图像（就是他们自己的房子！）让人无法忽视
• 亲切且具体的消息读起来像真人写的，而不是群发邮件
• USPS 投递会触发“这很重要”的直觉

应用场景

行业	扫描内容	渲染内容	语气
泳池建造商	后院没有泳池	在他们的院子里添加泳池	亲切、令人向往
园林设计师	杂草丛生／枯萎的院子	修整一新的景观	亲切、有画面感
屋顶施工商	受损或老化的屋顶	新屋顶效果图	专业、紧迫
太阳能安装商	朝南的大面积屋顶	太阳能电池板效果图	专业、侧重节省成本
房地产经纪人	FSBO 或已过期的房源	布置好的室内效果图	专业、乐于助人
房屋改造商	过时的外观	现代化翻新效果图	热情、焕然一新

所有场景都使用相同的两次工具调用。变化的只有扫描内容、渲染效果、语气和消息。

---

消息生成

你有三种方式来撰写手写消息。请根据你的设置选择：

选项 A — 使用 Cloudflare AI 的 generate_message 工具

设置 CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN。服务会通过 Cloudflare Workers AI 调用 Llama 3.1 8B Instruct，并使用 Postals 久经验证的语气配置。返回可直接使用的消息。

"env": {
  "POSTALS_API_KEY": "...",
  "CLOUDFLARE_ACCOUNT_ID": "...",
  "CLOUDFLARE_API_TOKEN": "..."
}

选项 B — 不使用 AI 的 generate_message 工具（推荐大多数 Agent 使用）

不要设置 CF 变量。该工具会返回结构化提示词（系统提示词 + 用户提示词），供你的 Agent 使用自己的大模型。由于调用该工具的 Agent 本身已经是大模型（Claude、GPT 等），生成的消息至少不逊于 Llama 3.1，通常还更好。

选项 C — compose_postcard_message MCP 提示词

一种 MCP 提示词原语（不是工具）。Claude Desktop 会在斜杠命令菜单中显示它。Agent 会将 Postals 的指南直接注入上下文并撰写消息。

选项 D — 让 Agent 自行撰写消息

完全跳过 generate_message。你的 Agent 已经会写消息。只需将消息直接传递给 send_postcard。

---

图像处理

front_image_url 必须是指向 PNG 或 JPEG 的公开 HTTPS URL。服务会获取图像，将其上传到我们的印刷合作伙伴，并制作定制卡片。

推荐规格

• 格式： PNG 或 JPEG
• 方向： 横向（宽大于高）
• 尺寸： 2100 × 1500 px（300 DPI 下为 7×5 英寸）——印刷品质
• 最低尺寸： 1050 × 750 px
• 最大文件大小： 10 MB
• 可访问性： 公开 URL，无身份验证标头，不使用 TTL 较短的签名 URL

常见来源

来源	示例
你自己的 CDN / S3 / Cloudflare R2	https://cdn.yoursite.com/renders/xyz.png
AI 图像生成结果	大多数服务都会返回公开 URL
静态模板	托管在你网站上的预先设计公司卡片
Recraft V3（将在未来版本中推出）	generate_card_image 工具会返回一个 URL

没有图像？

将 POSTALS_DEFAULT_CARD_IMAGE 设置为你的品牌备用图像。每次调用未提供 front_image_url 时，都会使用默认图像。这非常适合所有卡片使用相同模板的商业场景。

---

测试模式

零成本、零风险测试。在环境变量中设置 POSTALS_TEST_MODE=true。

启用后：

• 所有输入仍会正常验证（州代码、ZIP 格式、消息长度、HTTPS URL）
• 每日限额计数器会递增（因此你可以测试支出控制）
• 速率限制器会强制执行 2 秒延迟（因此你可以测试时序）
• 不会调用履约 API——不会打印卡片，也不会产生费用
• 响应包含 test_mode: true 和 mock_order_id

{
  "success": true,
  "test_mode": true,
  "message": "Test mode — no card sent. Set POSTALS_TEST_MODE=false to send real cards.",
  "mock_order_id": "test-1713099999999",
  "recipient": "Jane Smith",
  "estimated_delivery": "3-5 business days via USPS",
  "cards_sent_today": 3,
  "daily_limit": 25
}

最佳实践： 先设置 POSTALS_TEST_MODE=true，确认 Agent 的工具调用看起来正确，然后再关闭该设置，进行首次实际寄送。

---

支出控制

Agent 会自主运行。错误配置加上没有限额，可能导致昂贵的故障。此服务内置四层安全措施：

1. 每日限额（POSTALS_DAILY_LIMIT，默认值为 50）

每天寄送卡片数量的硬性上限。计数器于 UTC 午夜重置。达到上限后：

isError: true
"Daily limit reached (25/25). Resets at midnight UTC. Adjust with POSTALS_DAILY_LIMIT env var."

开发期间将此值设低（5–10）。确认 Agent 运行可靠后再调高。

2. 速率限制器（每次寄送至少间隔 2 秒）

严格的服务端限流。如果你连续快速调用两次 send_postcard，第二次调用会等待 2 秒后再执行。这可以防止 API 滥用，并让你有时间察觉失控行为。

3. 幂等键

在 send_postcard 参数中传入 idempotency_key。相同的键会得到相同结果，不会重复寄送。键会缓存 24 小时。

await send_postcard({ ..., idempotency_key: "prospect-123-oak-st" });
// If the network hiccups and your agent retries with the same key,
// you get back the original response — no second card mailed.

对于自主运行的 Agent 至关重要。 否则，网络超时后重试可能导致寄出两张明信片。

4. 测试模式

见上文。开发期间的双重保险。

v1.1 版本即将推出

预付钱包（预先充值、逐步扣款），按卡片计费；带月度上限的自动充值；三种资金来源（Stripe、USDC/WLD 加密货币、Agent 自行充值）；即时暂停（从控制面板撤销 API 密钥）；以及在每个响应中跟踪余额，让 Agent 能够自我调节。

---

错误处理

错误会返回 isError: true，并附带可执行的消息，供 Agent 转达给用户。示例：

场景	错误消息
缺少 API 密钥	"POSTALS_API_KEY not set. Add it to your MCP server env config. Get a key at postals.ai/developers."
州代码无效	"Invalid state code \"ZZ\". Must be a 2-letter US state (e.g. CA, NY, TX)."
ZIP 无效	"Invalid ZIP \"ABC12\". Must be 5 digits (e.g. 78701) or 5+4 (e.g. 78701-1234)."
缺少图片且没有默认图片	"No card image. Provide front_image_url or set POSTALS_DEFAULT_CARD_IMAGE env var."
图片 URL 不是 HTTPS	"front_image_url must be an HTTPS URL."
缺少回邮地址	"No return address. Provide return_address or set POSTALS_SENDER_* env vars."
达到每日限额	"Daily limit reached (25/25). Resets at midnight UTC. Adjust with POSTALS_DAILY_LIMIT env var."
获取图片失败	"Send failed: Cannot fetch image from URL (HTTP 404). Ensure the URL is publicly accessible."
履行错误	"Send failed: <classified error — address, message length, auth, etc.>"

错误消息旨在让 Agent 阅读后自行修正问题，或用通俗易懂的语言向用户转达解决方法。

---

配置参考

所有配置均通过 MCP 客户端配置中的环境变量设置。

变量	必需	默认值	说明
POSTALS_API_KEY	是	—	从 postals.ai/developers 获取的 API 密钥。
POSTALS_SENDER_NAME	建议	—	默认寄件人全名
POSTALS_SENDER_ADDRESS	建议	—	默认寄件人街道地址
POSTALS_SENDER_CITY	建议	—	默认寄件人所在城市
POSTALS_SENDER_STATE	建议	—	默认寄件人 2 个字母的州代码
POSTALS_SENDER_ZIP	建议	—	默认寄件人 ZIP
POSTALS_DEFAULT_CARD_IMAGE	建议	—	默认卡片正面图片的 HTTPS URL（调用方未提供 front_image_url 时使用）
POSTALS_HANDWRITING_STYLE	可选	Joyful Jennifer	默认手写字体
POSTALS_DAILY_LIMIT	可选	50	每日最多发送的卡片数量。开发期间请设为较低值。
POSTALS_TEST_MODE	可选	false	true = 跳过实际发送，返回模拟响应
CLOUDFLARE_ACCOUNT_ID	可选	—	启用通过 Llama 3.1 生成 AI 消息
CLOUDFLARE_API_TOKEN	可选	—	与 CLOUDFLARE_ACCOUNT_ID 配合使用时为必需

单次调用覆盖项： send_postcard 参数中的 return_address、handwriting_style 和 front_image_url 会覆盖该次发送的环境变量默认值。

---

手写风格

默认值：Joyful Jennifer — 温暖、友好、自然的手写风格。

常见手写风格选项：

• Joyful Jennifer — 温暖、友好的女性风格
• Tarzan — 醒目、有活力
• Casual Craig — 随性、男性风格
• Fancy Fiona — 优雅的手写体
• Precise Paul — 工整、商务风格

在工具参数中将确切的风格名称作为 handwriting_style 传入，或全局设置 POSTALS_HANDWRITING_STYLE。若要查看账户可用的全部风格，请浏览 postals.ai/developers 上的可用风格。

---

故障排除

Claude Desktop 未显示工具

1. 完全退出 Claude Desktop（通过菜单 → 退出，而不只是关闭窗口），然后重新打开。配置更改需要完全重启才能生效。
2. 确认配置 JSON 有效（没有尾随逗号，且引号正确）。
3. 在 macOS 上，检查路径：~/Library/Application\ Support/Claude/claude_desktop_config.json。
4. 在终端中手动运行 npx -y postals-mcp。如果报错，请先解决该问题。

npx -y postals-mcp 一直挂起

这是预期行为 — 它正在等待通过 stdin 输入 MCP 协议内容。要独立测试，请使用随附的测试脚本：

cd src/MCP/postals-mcp
npm install
npm run build
POSTALS_API_KEY=test POSTALS_TEST_MODE=true node test-harness.mjs

“POSTALS_API_KEY not set”

环境变量未传递给服务端。请检查：

• MCP 客户端配置中的 env 块是否设置正确
• 编辑配置后是否重启了客户端
• JSON 中的密钥是否用引号括起来

“Cannot fetch image from URL”

图片 URL 必须满足以下条件：

• 是公开的 HTTPS URL（不能使用 http://、file:// 或 data:）
• 无需身份验证标头或 Cookie 即可访问
• 返回有效的 PNG 或 JPEG，且 Content-Type 为 image/png 或 image/jpeg

使用 curl -I <url> 测试——应返回 200，且内容类型应为有效的图片类型。

卡片未送达

1. 是否将 POSTALS_TEST_MODE 设为了 true？如果是，则不会实际寄出卡片。请移除该变量，或将其设为 false。
2. 在 postals.ai/developers 查看调用返回的 order_id 对应的订单状态。
3. 卡片在寄出后需 3–5 个工作日送达（不是从下单时开始计算）。打印会在 1 个工作日内完成。

速率限制器似乎太慢

2 秒的最短间隔是有意设置且不可更改的。它可以防止 API 滥用，并让你有机会发现失控行为。

---

常见问题

费用是多少？ 每张卡片 $4.99。无月度最低消费，无订阅费用。每月订购 101 张起可享批量折扣（v1.1）。

多久能送达？ 邮寄后通过 USPS 在 3–5 个工作日内送达。API 调用后 1 个工作日内打印并寄出卡片。

真的是真人手写吗？ 是的。定制机器人手持真笔，用真实墨水在真实纸张上书写。收件人无法察觉这是机器人书写的。

手写邮件的打开率是多少？ 通常比印刷直邮高 5–10 倍。正面个性化图片（由 AI 生成）还能进一步提高回复率。

支持哪些国家/地区？ 美国地址每张 $4.99，通过 USPS 在 3-5 个工作日内送达。支持国际地址，但送达时间更长，价格因目的地而异。国际费率请联系我们。

可以寄信件或包裹吗？ v1.0 仅支持明信片。信件、信封和贺卡计划在后续版本中推出。

支持哪些图片格式？ PNG 或 JPEG。建议使用横向 7×5 英寸（300 DPI 下为 2100×1500 px）的图片。

可以取消寄送吗？ v1.0 不支持。在打印时限内取消（cancel_postcard 工具）计划在 v1.1 中推出。

可以查询投递状态吗？ v1.0 不支持。check_order_status 工具计划在 v1.1 中推出。

如果 Agent 有 bug，试图寄出 1000 张卡片怎么办？ 开发时将 POSTALS_DAILY_LIMIT 设为较低值（5–10）。发送第 11 张时会返回错误，不会寄出。配合重试时使用的 idempotency_key 和 2 秒速率限制，可覆盖最常见的三种失控情况。v1.1 将增加带硬性余额上限的钱包——余额一旦降至 $0，Agent 就会停止。

Agent 能用加密货币收入为自己充值吗？ 计划在 v1.1 中推出。提供三种充值方式：Stripe（由人类付款）、加密货币充值（由人类发送 USDC/WLD）和 Agent 自行充值（Agent 从自己的钱包支出，由人类授权并设置月度上限）。这将支持完全自主的业务闭环：Agent 赚取加密货币 → 为钱包充值 → 寄出卡片 → 达成交易 → 赚取更多。

可以用于商业用途吗？ 可以。采用 MIT 许可证。卡片按次计费，无许可费用。

与 Lob 或 PostGrid 相比，价格如何？ Lob 和 PostGrid 提供印刷明信片，价格为 $0.48–$0.77。我们提供的是手写明信片，价格为 $4.99。这是不同的产品。对于需要手写明信片的外联场景（房地产、家庭服务、高客单价销售），打开率和回复率的大幅提升足以抵消手写溢价。

多个 Agent 可以共用一个 API 密钥吗？ 可以，但它们共用每日限额。建议每个 Agent 使用单独的密钥以隔离限额（v1.1+ 支持每个账户使用多个密钥）。

这能与 langchain / crewai / autogen 配合使用吗？ 任何支持 MCP 客户端的框架都可以使用。TypeScript/Python MCP SDK 可以像连接其他 MCP 工具一样连接此服务。代码请参阅自定义 Agent部分。

会记录哪些数据？ 仅向 stderr 输出结构化 JSON 事件。我们会记录：事件名称、时间戳、城市/州（用于调试）、计数器数值和订单 ID。我们绝不会记录：完整地址、完整消息、收件人姓名、API 密钥，或包含身份验证令牌的图片 URL。

---

后续计划

当前版本：v1.0 — 每张卡片 $4.99。

v1.1 即将推出（2–3 周内）：

• 在 postals.ai/developers 注册 Postals 开发者账号
• 预付钱包（提前付款，按需扣费），支持 Stripe + USDC 加密货币
• check_balance 工具 — Agent 可在每条响应中查看余额
• check_order_status 工具 — 查询履约状态
• cancel_postcard 工具 — 可在打印时间窗口内取消
• 无需外部账号

v2.0 即将推出（6–8 周内）：

• 在 postals.ai/developers 提供完整的开发者仪表板
• 设置每月上限的自动充值
• Webhook 事件（card_sent、low_balance、daily_limit_hit）
• 每个账号支持多个 API 密钥
• 路径 3： Agent 从自己的加密货币钱包自筹资金（需经人工授权）
• USPS CASS 认证的地址验证
• 阶梯式批量定价（101–500：$4.49，501–2000：$3.99，2000+：定制价格）

v3.0+ 即将推出：

• generate_card_image 工具 — 使用 Recraft V3 AI 生成卡片图片
• 卡片模板库（感谢、生日、商务、房地产等）
• 多服务商履约（手写 + 印刷选项）
• 国际邮件（加拿大、英国、欧盟）
• 适用于高吞吐量工作流的批量发送工具
• 信件和信封

请访问 postals.ai 了解更多路线图和架构信息。

---

参与贡献

欢迎在 GitHub 仓库提交问题和 PR。对于重大更改，请先提交问题进行讨论。

运行测试脚手架：

npm install
npm run build
POSTALS_API_KEY=test POSTALS_TEST_MODE=true node test-harness.mjs

所有 37 项检查都应通过。

---

链接

• 网站： postals.ai
• npm： postals-mcp
• GitHub： github.com/coopergwrenn/postals-mcp
• agents.md（面向 Agent）：postals.ai/agents.md
• SKILL.md（随附的技能文件）：./SKILL.md
• Model Context Protocol： modelcontextprotocol.io

---

许可证

MIT © Postals