eShipz跟踪MCP服务器
模型上下文协议（MCP）服务器，通过eShipz API提供装运跟踪功能。该服务器使Claude Desktop能够通过智能、状态感知的格式跟踪多个运营商的包裹。
特性
- 📦 跨多个承运商跟踪货物
- 🎯 状态感知输出格式
- ✅ 自动状态检测（已交付、在途、异常等）
- 🌍 基于位置的更新
- 📊 事件计数和时间线跟踪
- 🔐 通过环境变量实现安全的API令牌管理
先决条件
- Python 3.12或更高版本
- 紫外线 包管理器
- eShipz API代币
- Claude桌面应用程序
安装
- 克隆存储库：
git clone https://github.com/YOUR_USERNAME/mcp-eshipz.git
cd mcp-eshipz- 创建一个
.env项目根目录中的文件：
API_BASE_URL=https://app.eshipz.com
ESHIPZ_TOKEN=your_eshipz_api_token_here- 安装依赖项：
uv sync配置
将服务器添加到Claude Desktop配置文件中：
窗户： %APPDATA%\Claude\claude_desktop_config.json\ macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"eshipz_tracking": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\mcp-eshipz",
"run",
"main.py"
]
}
}
}替换 C:\\path\\to\\mcp-eshipz 根据您的实际项目路径。
用法
配置服务器并重新启动Claude Desktop后，您可以要求Claude跟踪软件包：
- “轨道包 "
- “追踪号ABC123的状态如何？”
- “检查跟踪XYZ789的交货状态”
- “分析运营商绩效”
- “使用所有必填字段的有效值创建新发货”
- “案件前分配”
注：所有功能的必填字段请参阅eShipz的API文档
发货查询工作流（可重复使用的响应数据）
服务器现在支持一次取数，多次查询流量进行发货分析。
- 跑
query_shipments提取货物并创建可重复使用的query_id背景。 - 重复使用相同的
query_id和query_shipments_followup用于：
- 滞留装运检查(
intent="stuck") - 分组摘要(
intent="aggregate",group_by="status"|"carrier"|"sub_status"|"age_bucket") - 筛选列表(
intent="list"带可选过滤器）
- 使用
get_shipment_details_from_query通过以下方式从缓存上下文中获取特定装运awb或order_id.
这让Claude回答了同一API回复中的多个后续问题，而无需每次都重新提问。
向后兼容
get_shipments仍然适用于滞留装运报告。- 它现在在内部使用共享发货规范化/卡住逻辑，并包括
Query ID输出用于后续分析。
查询上下文行为
- 查询上下文在内存缓存条目中是短暂的。
- 如果查询id过期，请重新运行
query_shipments为了获得新鲜感query_id. - 缓存优化环境变量：
SHIPMENT_QUERY_TTL_SECONDS（默认值：1200)SHIPMENT_QUERY_MAX_CONTEXTS（默认值：25)SHIPMENT_QUERY_MAX_RECORDS（默认值：2000)
发展
在本地运行服务器进行测试：
uv run main.py项目结构
mcp-eshipz/
├── main.py # Main MCP server implementation
├── pyproject.toml # Project dependencies
├── .env # Environment variables (not in git)
├── .gitignore # Git ignore rules
└── README.md # This file依赖项
httpx-异步HTTP客户端mcp-模型上下文协议SDKpython-dotenv-环境变量管理
支持
对于问题或疑问，请在GitHub上打开问题。