UPS MCP 服务器

MIT License Node.js 20+ MCP TypeScript npm

一个用于 UPS 货运和物流 API 的 Model Context Protocol 服务器。使 AI 代理能够创建货件、追踪包裹、获取运费、验证地址、安排取件以及查找 UPS 网点。

快速安装

添加到您的 MCP 配置中（~/.cursor/mcp.json、.cursor/mcp.json 或 claude_desktop_config.json）：

{
  "mcpServers": {
    "ups": {
      "command": "npx",
      "args": ["-y", "ups-mcp"],
      "env": {
        "UPS_CLIENT_ID": "your_client_id",
        "UPS_CLIENT_SECRET": "your_client_secret",
        "UPS_ACCOUNT_NUMBER": "123456",
        "UPS_ENVIRONMENT": "sandbox"
      }
    }
  }
}

在 UPS 开发者门户获取您的凭据。

工具

工具	描述
`create_shipment`	创建货件并生成运输标签
`void_shipment`	取消货件并作废其标签
`track_package`	追踪包裹并获取完整活动历史记录
`get_rates`	获取所有可用服务的运费
`get_time_in_transit`	获取预计送达日期
`validate_address`	验证美国/波多黎各地址
`schedule_pickup`	安排包裹取件
`cancel_pickup`	取消已安排的取件
`find_locations`	查找附近的 UPS 门店和投递点

先决条件

Node.js 20+
UPS 开发者门户凭据（开始使用）
UPS 账号（用于货运和计费）

安装

npx ups-mcp

或全局安装：

npm install -g ups-mcp

配置

环境变量

变量	必需	描述
`UPS_CLIENT_ID`	是	来自 UPS 开发者门户的 OAuth 客户端 ID
`UPS_CLIENT_SECRET`	是	OAuth 客户端密钥
`UPS_ENVIRONMENT`	否	`sandbox`（默认）或 `production`
`UPS_ACCOUNT_NUMBER`	否	6 位 UPS 账号（货运/计费必需）

客户端	配置文件
Cursor (项目)	`.cursor/mcp.json`
Cursor (全局)	`~/.cursor/mcp.json`
Claude Desktop	`claude_desktop_config.json`
VS Code	`.vscode/mcp.json`

使用示例

创建货件

"通过 UPS Ground 将一个 5 磅的包裹从 123 Main St, Atlanta GA 30301 寄往 456 Oak Ave, Los Angeles CA 90001"

获取运费

"从纽约到芝加哥寄送一个 10 磅的包裹运费是多少？"

追踪包裹

"追踪包裹 1Z999AA10123456784"

验证地址

"1600 Pennsylvania Ave NW, Washington DC 20500 是有效地址吗？"

安排取件

"明天上午 9 点安排在我们的仓库取 3 个包裹"

开发

git clone https://github.com/roscoej/ups-mcp.git
cd ups-mcp
npm install
npm run build

使用 MCP Inspector 进行测试

npm run inspector

本地运行

cp .env.example .env
# Edit .env with your credentials
npm run build
node dist/index.js

架构

src/
├── index.ts            # Entry point (stdio transport)
├── config.ts           # Environment variable resolution
├── server.ts           # MCP server factory
├── client/
│   ├── auth.ts         # OAuth 2.0 token manager
│   ├── http.ts         # HTTP client with retry + error handling
│   └── errors.ts       # Structured error types
├── tools/
│   ├── tracking.ts     # track_package
│   ├── shipping.ts     # create_shipment, void_shipment
│   ├── rating.ts       # get_rates, get_time_in_transit
│   ├── address.ts      # validate_address
│   ├── pickup.ts       # schedule_pickup, cancel_pickup
│   ├── locator.ts      # find_locations
│   ├── builders.ts     # Shared request payload builders
│   ├── constants.ts    # UPS API codes and enumerations
│   └── schemas.ts      # Zod input schemas
└── types/
    ├── config.ts       # Server configuration
    ├── shipping.ts     # Shipment types + service codes
    ├── tracking.ts     # Tracking types
    ├── rating.ts       # Rating types
    ├── address.ts      # Address validation types
    └── pickup.ts       # Pickup types

安全性

您的 API 凭据属于敏感信息。切勿将其提交到版本控制系统中。请使用环境变量或密钥管理器。

免责声明

本项目是一个独立的、非官方的第三方工具。它与联合包裹服务公司 (UPS) 或其任何子公司没有关联、认可、赞助或以任何方式正式连接。

"UPS" 和 UPS 品牌标志是联合包裹服务公司 (United Parcel Service of America, Inc.) 的注册商标。所有其他商标均为其各自所有者的财产。使用这些名称仅用于识别和互操作性目的，并不暗示认可。

本软件按“原样”提供，不提供任何形式的保证。您需自行承担以下责任：

遵守 UPS 技术协议以及所有适用的 UPS 服务条款、费率限制和可接受使用政策。
保护您的 API 凭据和 UPS 账号安全。
通过此工具在您的 UPS 账号下进行的所有活动。
遵守您所在司法管辖区的所有适用法律和法规。

作者和贡献者对因使用本软件或通过其访问的 UPS API 而产生的任何损害不承担任何责任。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

许可证

MIT

Install Server

A

license - permissive license

A

quality

C

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

UPS MCP Server