寄件服务MCP Server

提供寄件订单管理、地址簿查询等功能的Model Context Protocol (MCP) Server，支持通过HTTP API对接远程寄件服务。

功能特性

🏠 地址簿管理

• 查询用户保存的地址簿数据

• 支持关键词搜索（姓名、电话、地址）

• 标识默认地址

📦 寄件订单管理

• 创建新的寄件订单

• 分页查询订单列表

• 查询订单详细信息

• 支持多种服务类型（标准/快速/经济）

• 订单状态追踪

🔍 高级查询

• 按日期范围过滤订单

• 按订单状态过滤

• 分页浏览订单列表

• 完整物流追踪记录

🌐 API集成

• 支持HTTP API对接真实寄件服务

• 灵活的配置管理（命令行参数/环境变量）

• Mock模式用于开发和测试

• 完善的错误处理和重试机制

Related MCP server: ShipBob API MCP Server

安装

使用 uvx（推荐）

使用 pip

注意: 新发布的包可能需要几分钟时间在各个 PyPI 镜像中同步。如果遇到包未找到的错误，请稍等片刻再试，或使用 pip 安装后直接使用命令。

使用方法

配置API参数

方法1: 通过命令行参数

方法2: 通过环境变量

方法3: 在Claude Desktop中配置

使用 uvx（推荐，无需预安装）:

使用已安装的包:

使用模拟模式（开发测试）:

开发模式运行

生产模式运行

工具列表

1. 地址簿查询 (query_address_book)

查询用户的地址簿信息

参数:

• search_key (可选): 搜索关键词，可以搜索姓名、电话或地址

返回:

2. 创建寄件订单 (create_shipping_order)

创建新的寄件订单

参数:

• sender_name: 寄件人姓名

• sender_phone: 寄件人电话

• sender_address: 寄件人地址

• receiver_name: 收件人姓名

• receiver_phone: 收件人电话

• receiver_address: 收件人地址

• package_type: 物品类型

• package_weight: 重量(kg)

• package_size: 尺寸(长x宽x高,cm)

• service_type: 服务类型(标准/快速/经济)

返回:

3. 查询订单列表 (list_shipping_orders)

分页查询寄件订单列表

参数:

• page_size: 每页数量（默认10）

• page_number: 页码，从1开始（默认1）

• start_date: 开始日期(YYYY-MM-DD格式)

• end_date: 结束日期(YYYY-MM-DD格式)

• status: 订单状态过滤

返回:

4. 查询订单详情 (get_order_detail)

获取订单详细信息

参数:

• order_id: 订单号

• detail_level: 详情级别(basic/full)

返回:

订单状态说明

• 待取件: 订单已创建，等待快递员取件

• 运输中: 包裹正在运输途中

• 派送中: 包裹已到达目的地，正在派送

• 已签收: 包裹已成功签收

• 已退回: 包裹已退回寄件人

• 已取消: 订单已取消

服务类型说明

• 标准: 48小时送达，费用标准

• 快速: 24小时送达，费用1.5倍

• 经济: 72小时送达，费用0.8倍

开发

项目结构

代码说明

服务器使用了以下主要组件：

• FastMCP: MCP协议的Python实现

• 数据模型: 使用dataclass定义订单、地址等数据结构

• 枚举类型: 定义订单状态和服务类型

• 模拟数据: 内存中存储示例数据，实际应用中可替换为数据库

扩展功能

可以进一步扩展的功能：

• 集成真实的快递API

• 添加数据库持久化

• 实现用户认证

• 添加订单状态更新功能

• 集成支付功能

• 添加物流追踪API

许可证

MIT License

贡献

欢迎提交Issue和Pull Request来改进这个项目。