摘要
USPS API 为发货人提供:验证美国地址和查找邮政编码,比较国内和国际价格,获取交货天数和运输选项,跟踪包裹,查找邮局、投递点和包裹储物柜。标签、退款、取件和 SCAN 表单包含在内但已关闭。来自 USPS 客户入门门户的应用程序的消费者密钥和密钥。
引导式设置
2 分钟将 USPS 连接到 Cursor
开始 AnythingMCP Cloud 免费试用,在引导式设置中连接 USPS,再把你的 MCP URL 添加到 Cursor。无需代码,也无需自行运行服务器。
无需信用卡 · 7 天试用 · 提供自托管方案
试试这样问
USPS 的示例提示
点击任意提示即可复制,然后粘贴到 Claude、ChatGPT、Cursor、Gemini、Copilot 或 OpenClaw 中,在该连接器上运行。
Claude 是 AI,可能会出错。请核对回答。
💡 没有安装?直接使用 cloud.anythingmcp.com。 登录,点击 Connectors → USPS,粘贴你的凭据,生成一个 MCP API 密钥,完成。无需 Docker,无需
git clone,无需本地服务器。
USPS + Cursor
USPS API 为发货人提供:验证美国地址和查找邮政编码,比较国内和国际价格,获取交货天数和运输选项,跟踪包裹,查找邮局、投递点和包裹储物柜。标签、退款、取件和 SCAN 表单包含在内但已关闭。来自 USPS 客户入门门户的消费者密钥和密钥。
前提条件
请查看连接器中包含的完整设置说明(在选择连接器时可在应用内商店中查看)。此连接器所需的环境变量为:
USPS_CLIENT_ID, USPS_CLIENT_SECRET, USPS_API_HOST
第一步 — 获取凭据
设置大约需要 15 分钟。
- 打开 USPS 客户入门门户 https://cop.usps.com/cop-navigator?wf=API,使用你的 USPS 商业账户登录,或在此处创建一个。该门户为 USPS API 准备账户。
- 在门户顶部选择 My Apps 并添加一个应用程序。
- 打开该应用程序。在 Credentials 中将 Consumer Key 复制到
USPS_CLIENT_ID,将 Consumer Secret 复制到USPS_CLIENT_SECRET。 - 在
USPS_API_HOST中选择 API 地址:生产环境https://apis.usps.com,或邮件发送者的测试环境https://apis-tem.usps.com。两者都使用相同的生产凭据。在测试主机上生成的标签带有水印且不会收费。USPS 为每个 API 发布测试主机,除了跟踪,因此在主要跟踪时请保持生产状态。 - 可选,对于标签和合同价格:你的 CRID、Mailer ID 和企业支付账户号码在
USPS_CRID、USPS_MID和USPS_EPS_ACCOUNT_NUMBER中。你的商业客户网关账户的商业服务管理员拥有这些信息。
连接器将消费者密钥和密钥发送到所选主机的 /oauth2/v3/token(客户端凭据),并获取一个有效期约 8 小时的承载令牌,连接器会自行重用和续订。
新应用程序可能使用的内容:每个应用程序都以 USPS 默认产品开始:OAuth、地址、国内价格、国际价格、位置、服务标准、运输选项和跟踪。因此,地址、价格、交货天数、运输选项、跟踪、邮局和投递地点可以立即使用。承运人取件、付款、标签和国际标签以及 SCAN 表单需要 USPS 批准:通过电子邮件联系我们页面 (https://emailus.usps.com/s/usps-APIs) 提出 USPS API 服务请求。标签 API 还需要注册 USPS Ship(外发和退回标签)和一个支付邮资的 企业支付账户(EPS)。包裹储物柜 (usps_find_parcel_lockers) 和国际服务标准 (usps_get_international_service_standard) 有自己的作用域;如果它们返回 403,请以相同方式向 USPS 请求。
从哪里开始:usps_get_city_state 使用邮政编码证明连接。要获取报价,usps_search_shipping_options 一次返回每项服务的价格和交货日期;usps_search_domestic_prices 和 usps_search_international_prices 提供价格细分和额外服务。
地址:usps_validate_address 标准化美国地址并返回 ZIP+4、DPVConfirmation(Y 确认,D 缺少次要号码,S 次要号码未确认,N 未确认)、business(Y 或 N)和 vacant。usps_get_zip_code 查找城市和州的街道的邮政编码,usps_get_city_state 查找邮政编码的城市和州。州是两个字母的代码;仅涵盖美国地址(包括领土和军事地址)。
价格:包裹以磅为单位称重,以英寸为单位测量;信件、平信和卡片以盎司为单位称重。price_type COMMERCIAL 是你在线购买标签时支付的费用,RETAIL 是邮局柜台价格,CONTRACT 需要 account_type 和 account_number。usps_search_domestic_prices 返回 rateOptions,其中包含 totalBasePrice、totalPrice 和额外服务;usps_list_domestic_prices 列出每个符合条件的产品及其 SKU、rateIndicator 和 processingCategory,这些值是标签请求所需的。usps_search_letter_prices 为优先邮件信件、平信和明信片定价。国外:usps_search_international_prices(可选地按每项商品的关税和税费),usps_list_international_prices 和 usps_search_international_letter_prices。邮寄日期可以是今天到 7 天后。金额为美元。USPS_GROUND_ADVANTAGE 替代了优先包裹服务和零售地面。
交货天数:usps_get_delivery_estimates 提供邮寄日的预定交货日期,包含接受截止时间(cutOffTime,HHMM 本地时间);usps_get_service_standards 提供每个邮件类别的标准天数;usps_get_international_service_standard 提供诸如“预计在 5-9 个工作日内交货”的句子。服务标准是目标,而不是保证。
跟踪:usps_track_package 用于一个号码,usps_track_packages 可同时跟踪最多 35 个。两者都使用跟踪 3.2;遗留的跟踪 3.0 API 将于 2027 年 7 月 31 日退役。答案包含 statusCategory、statusSummary、trackingEvents(eventTimestamp 为事件的本地时间,GMTTimestamp 为 UTC)、deliveryDateExpectation 和 uniqueTrackingID。批量请求在某些号码失败时返回 HTTP 207,每个失败的号码都有自己的 error。usps_register_tracking_notifications 注册最多 3 个电子邮件地址以接收跟踪电子邮件,usps_request_proof_of_delivery 会将送达证明信通过电子邮件发送;两者都需要跟踪答案的 uniqueTrackingID,从 USPS 发送电子邮件且不收费。
位置:usps_find_post_offices 按邮政编码、城市和州、地址或坐标(半径为英里,默认 20)进行搜索,并列出每项服务的工作时间;usps_find_dropoff_locations 列出按目的地邮政编码的包裹选择、USPS Connect 和包裹服务的投递入口设施;usps_find_parcel_lockers 查找包裹储物柜。
取件:usps_check_pickup_eligibility 和 usps_get_pickup 仅用于读取。usps_schedule_pickup 预定免费的承运人取件(周一至周六),usps_cancel_pickup 取消取件;两者都已关闭。这里无法更改取件:取消并重新预定一个新的。
标签(已关闭):每个标签调用都需要支付授权令牌。usps_create_payment_authorization 使用你的 CRID、Mailer ID 和 EPS 账户返回 paymentAuthorizationToken;将其传递给 usps_create_label、usps_create_return_label、usps_create_international_label、usps_cancel_label 或 usps_cancel_international_label。标签以 JSON 格式返回:labelMetadata 包含跟踪号码和邮资,labelImage 为 base64 格式(默认 4x6 PDF)。创建标签会从 EPS 账户购买邮资。取消请求返回 CANCELED,或 DISPUTED,当 USPS 开启退款请求时返回 disputeId。usps_get_payment_account 读取账户,并在给定 amount 时告知资金是否充足。usps_create_scan_form 将多个标签放在一个 PS 表单 5630 上,以便单次接受扫描记录每个包裹。仅在 USPS 批准标签 API 后启用这些工具,并先在测试主机上尝试。
错误:失败以 error 形式返回,包含 code、message 和一个 errors 列表(title、detail、source.parameter)。400 表示字段错误;401 表示凭据错误或令牌过期;403 表示应用程序没有该 API(超出默认产品范围);404 表示 USPS 未找到任何内容,例如未知的跟踪号码。
限制:每个应用程序每小时有调用配额;429 表示已用完,直到下一个小时。USPS 可通过电子邮件联系我们页面请求提高配额。日期格式为 YYYY-MM-DD。
第二步 — 安装适配器
curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d
第三步 — 在 Cursor 中添加连接器
你的服务器 URL: 在 AnythingMCP 中打开 MCP Servers → 此连接器所在的服务器,复制它的 URL(
https://cloud.anythingmcp.com/mcp/…)。本指南中出现YOUR_SERVER_ID的地方都用它替换。
Cursor 从 ~/.cursor/mcp.json 读取 MCP 服务器。添加以下条目:
{
"mcpServers": {
"anythingmcp": {
"url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
"headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
}
}
}
- 在 AnythingMCP 的 MCP Servers → 你的服务器 → API keys 中创建 MCP API 密钥,并用它替换
YOUR_MCP_API_KEY。 - 保存文件并重启 Cursor。
- 打开 Cursor → Settings → MCP,确认
anythingmcp已列出并处于已连接状态。 - 开始对话 — 智能体现在可以调用
USPS的工具。
可用工具
| 工具 | 功能 |
|---|---|
usps_validate_address | 验证并标准化一个美国地址。返回 USPS 标准格式的 address(streetAddress、city、state、ZIPCode、ZIPPlus4)… |
usps_get_city_state | 查找 5 位邮政编码的城市和州。返回 city(大写)、state(两个字母)和 ZIPCode。便宜的调用,用于… |
usps_get_zip_code | 查找城市和州中街道地址的邮政编码和 ZIP+4。返回标准化街道的 address、city、state… |
usps_search_domestic_prices | 为国内包裹定价,包含额外服务。返回 rateOptions,每个符合条件的产品一个,包含… |
usps_list_domestic_prices | 列出每个国内包裹符合条件的产品,包含其基本价格和没有额外服务。返回 rateOptions,包含… |
usps_search_letter_prices | 为优先邮件信件、平信(大信封)或在美国寄送的明信片定价。返回 totalBasePrice 和 rates(SKU… |
usps_search_international_prices | 为外发国际包裹定价,包含额外服务,并在请求时按每项商品的关税和税费。返回 rateOptions,每个符合条件的产品一个… |
usps_list_international_prices | 列出每个国际产品符合条件的外发包裹,包含基本价格和没有额外服务。返回 rateOptions,包含… |
usps_search_international_letter_prices | 为优先邮件国际信件、平信或明信片定价。返回 totalBasePrice、rates(SKU、description、price、fees)… |
usps_get_delivery_estimates | 估算在特定日期接受的邮件的交货日期。返回一个列表,每个邮件类别一个条目,包含 serviceStandard(天数)… |
usps_get_service_standards | 获取每个邮件类别在两个邮政编码之间的标准交货天数。返回一个列表,包含 mailClass、days… |
usps_get_international_service_standard | 获取国际邮件类别到某个国家的预计交货时间。返回 countryCode、mailClass 和… |
usps_search_shipping_options | 在一次调用中比较寄送一个包裹的每种方式:价格和交货承诺一起,国内或国际。返回… |
usps_track_package | 使用跟踪 3.2 跟踪一个 USPS 包裹。返回 trackingNumber、uniqueTrackingID、mailClass、status、statusCategory(例如… |
usps_track_packages | 使用跟踪 3.2 同时跟踪最多 35 个 USPS 包裹。每个号码返回一个结果,包含 trackingNumber、uniqueTrackingID… |
usps_register_tracking_notifications | 注册最多 3 个电子邮件地址以接收有关一个包裹的 USPS 跟踪电子邮件:预计交货更新、交货活动或所有更新。需要… |
usps_request_proof_of_delivery | 让 USPS 将送达证明信(或电子回执)通过电子邮件发送给最多 3 个收件人。需要… |
usps_find_post_offices | 查找靠近邮政编码、地址或坐标的邮局和其他零售地点,最近的优先。返回 locations,包含… |
usps_find_dropoff_locations | 查找可以投递 Parcel Select、USPS Connect 和包裹服务邮件的目的地入口设施,按目的地邮政编码… |
usps_find_parcel_lockers | 按邮政编码或城市和州查找 USPS 包裹储物柜。返回一个储物柜列表,包含 facilityID、locationName、locationAddress… |
usps_check_pickup_eligibility | 检查 USPS 是否在某个地址提供免费的承运人取件。地址符合标准时返回 200,包含 pickupAddress… |
usps_get_pickup | 通过确认号码获取预定的承运人取件。返回 confirmationNumber、pickupDate 和 carrierPickupRequest(地址… |
usps_get_payment_account | 检查企业支付账户或许可证。返回账户详细信息,并在给定 amount 时返回 sufficientFunds(真或假)… |
usps_create_payment_authorization | 获取每个标签调用所需的支付授权令牌:将你的企业命名为 PAYER 和 LABEL_OWNER,包含其 CRID、Mailer ID 和… |
usps_create_label | 购买邮资并创建国内运输标签,从支付授权令牌中的企业支付账户支付。返回… |
usps_create_return_label | 为客户创建一个国内退货标签,以便将包裹寄回(to_address 是你的退货地址,from_address 是客户)。… |
usps_cancel_label | 取消未使用的国内标签或请求邮资退款。返回 trackingNumber、status(CANCELED,或 DISPUTED 当退款… |
usps_create_international_label | 购买邮资并创建带有海关表单的国际标签(优先邮件国际服务、国际优先邮件… |
usps_cancel_international_label | 取消未使用的国际标签或请求邮资退款。返回跟踪号码、status(CANCELED 或 DISPUTED)和… |
usps_schedule_pickup | 预定一个免费的 USPS 承运人取件,适用于你地址的包裹(周一至周六;当天仅限至中部时间凌晨 2 点)。返回… |
usps_cancel_pickup | 通过确认号码取消预定的承运人取件。取消时返回 200。已安装但关闭:取消请求保留在… |
usps_create_scan_form | 创建一个 SCAN 表单(PS 表单 5630),将标签链接到一个条形码,以便在接受时进行单次扫描记录每个包裹。返回… |
示例提示
- "USPS 包裹 9400111899223197428490 在哪里?"
- "1600 Pennsylvania Ave NW, Washington DC 20500 是有效地址吗,它的 ZIP+4 是多少?"
- "比较 USPS 从 10001 到 94105 的 3 磅包裹的价格和交货日期,明天寄出。"
- "寄往多伦多的 2 磅包裹使用 USPS 优先邮件国际服务的费用是多少?"
- "查找 ZIP 60614 附近周六开放的邮局。"
常见问题
USPS 凭据来自哪里? 来自 USPS 客户入门门户中的应用程序(cop.usps.com),使用你的 USPS 商业账户登录:打开 My Apps,添加一个应用程序并复制其消费者密钥和消费者密钥。选择生产主机或邮件发送者的测试环境;两者都使用相同的凭据。
什么可以立即使用,什么需要 USPS 批准? 地址、价格、交货天数、运输选项、跟踪和位置可以与每个新应用一起使用。承运人取件、付款、标签和 SCAN 表单需要通过 USPS API 服务请求获得 USPS 批准;标签还需要 USPS Ship 和企业支付账户。
哪些工具安装时关闭? 购买或预定的工具:usps_create_payment_authorization、usps_create_label、usps_create_return_label、usps_cancel_label、usps_create_international_label、usps_cancel_international_label、usps_schedule_pickup、usps_cancel_pickup 和 usps_create_scan_form。在 USPS 批准后在连接器页面上启用它们,AI 应该使用它们。
Cursor 免费套餐支持自定义 MCP 服务器吗? 支持 — Hobby、Pro 和 Business 套餐均可使用 MCP。
下一步
这份指南对你有帮助吗?