express-tracker · 让你的 AI 帮你盯快递

English

这是一个 MCP 服务器（也可作为 Python 库嵌进你自己的后端）：给任何支持 MCP 的 AI 伴侣 / 助手加一个"盯快递"的能力。把单号甩给它，它登记；系统在后台自动巡查；到了、派送中、放驿站这类动态主动告诉你；签收后自动归档。

我们自己用了一段时间后整理开源的。两种用法：

两版共用同一个核心（service.py），行为完全一致。

功能

• 加单：单号 + 备注（这是什么）+ 收件手机后四位（顺丰 / 中通必填，不填永远"无物流信息"）。快递公司自动识别；写了中文名或拼音也能认。

• 自动巡查：间隔可调（5～720 分钟，默认 30）。签收后自动归档，不再查。

• 主动告知：巡查发现变化 → 嵌入版回调你的钩子 / MCP 版在下次工具调用时带回。中转流转这类小变化建议让 AI 自己判断值不值得开口（我们的提示词就是这么写的）。

• 单独暂停：某一单先不盯了，随时恢复。暂停的单不占额度，但手动查仍可。

• 省额度：同一单 15 分钟内重复查直接给缓存；查不到时不会拿空数据覆盖上次查到的好数据；缺尾号的中通 / 顺丰单不会反复白查。

• 额度统计：每向数据源发一次请求记一次，按天、按来源（巡查 / AI 查 / 你手动查）分账；用到你填的额度自动停巡查（手动查仍可）。

• 给 AI 的上下文块：context_block() 输出在途包裹的最新已知状态，塞进 AI 每轮上下文，它就不用自己反复调查询（我们实测：不注入的话 AI 会忍不住每次都查一遍）。

Related MCP server: Parcel App MCP Server

数据源开通（必做）

本项目不带任何真实的接口凭据。你需要自己开一个快递查询接口，把你自己的凭据填进配置。

默认：阿里云云市场「快递物流查询」类接口（推荐，个人可办）

1. 打开 market.aliyun.com，用淘宝 / 支付宝账号登录。

2. 搜「快递物流查询」，选一家评分高、带免费试用份数的（我们用的那家工具名叫「快递物流GET」「单号识别物流公司」，多家服务商是同一套接口）。

3. 点开通，选免费那档。

4. 进「买家中心 → 已购买的服务」，找到该服务的 MCP 页签，复制 streamableHttpUrl 里那个 URL（形如 http://mcpservergateway.market.alicloudapi.com/mcpnacos/cmapi000xxxxx/<一长串>）。这个 URL 含你的 appCode，是私人凭据，别分享、别提交到任何仓库。

5. 填进 config.json 的 provider_url。

免费额度通常是总共 N 次（不是每天），以购买页"剩余次数 / 有效期"为准。正式用一般几厘钱一单。把你买的额度填进 quota，用完系统会自动停巡查。

快递100（我们试过，个人拿不到）

快递100 开放平台注册后**必须企业认证（营业执照）**才能用接口，个人开发者过不了校验。providers/kuaidi100.py 留了骨架和签名逻辑，有企业资质的朋友可以补全后提 PR；我们没有账号，未联调。

自己接别的源

实现 providers/__init__.py 里的 Provider 协议（track() 和 identify()）两个方法即可。

安装

pip install git+https://github.com/lu7899112-source/express-tracker.git
# 自建版还要：
pip install "express-tracker[api] @ git+https://github.com/lu7899112-source/express-tracker.git"

配置

复制 examples/config.example.json 为 config.json，填好后用环境变量 EXPRESS_CONFIG 指向它（默认读当前目录的 config.json）。所有字段都可用环境变量覆盖：EXPRESS_PROVIDER_URL、EXPRESS_POLL_MINUTES、EXPRESS_QUOTA、EXPRESS_API_TOKEN、EXPRESS_DB、EXPRESS_USAGE。

config.json、*.db、usage.json 已在 .gitignore 里：你的凭据、单号、手机尾号永远只在你本机。

MCP 版（官方客户端）

Claude Desktop / Claude Code 配置示例见 examples/claude_desktop_config.example.json：

{ "mcpServers": { "express": { "command": "python", "args": ["-m", "express_tracker.mcp_server"], "env": { "EXPRESS_CONFIG": "/绝对路径/config.json" } } } }

工具：express_add / express_list / express_track / express_pause / express_remove。

关于"官端能不能巡查"，实话实说：

• 能巡查：MCP 服务器是客户端拉起的常驻进程，客户端开着它就活着，巡查就在它里面按你设的间隔跑；客户端关了巡查就停，下次打开接着跑。单子存在本地 SQLite 里，不会丢。

• 不能主动开口：官方客户端没有"服务器推消息给用户"的口子。所以巡查发现的变化会先攒着，你下次一开口、AI 一调用任何工具，结果末尾就会带一段"上次到现在的新动态"，AI 自然会告诉你。想要真正的主动推送，用嵌入版接你自己的通道。

嵌入版（自建前后端）

最小示例 examples/selfhosted_app.py：

from express_tracker.api import make_router, service
from express_tracker.config import Config

async def notifier(event):   # 巡查发现变化时被调用
    ...  # 塞进 AI 下一轮上下文 / 触发你的"服务器事件→AI 开口"通道 / 插系统消息

app.include_router(make_router(Config.load(), notifier=notifier))
asyncio.create_task(service().poll_loop())

接口（默认前缀 /api/express，Authorization: Bearer <api_token>）：

notifier 收到的 event：{"type":"express.update","label","status","last_time","last_msg","company","signed","trace","package"}。

建议：给它做一个贴合你自己前端的"外显"

本项目不带页面，是故意的：每家前端长得不一样，硬塞一套样式只会格格不入。但强烈建议自建的朋友做一个。我们自己的页面就是这么长出来的，接口一一对应，供参考：

几个小经验：暂停的卡淡一点、打个"已暂停"标；"需要收件手机后四位"这个状态要显眼，用户一眼知道该补什么；间隔输入框在手机上记得边输边存，只认失焦事件会漏（我们踩过）。

MCP 版也能对接你的后端：设 EXPRESS_API_URL 和 EXPRESS_API_TOKEN，它就改为调你的接口，不再内嵌巡查（这样 AI 的工具调用和你的页面看到的是同一份数据）。

官端实测

我们用 Claude Code 当官方客户端跑过一遍（只挂这一个 MCP，假数据源）：说"帮我盯着这个包裹，单号…，是猫粮" → 它调 express_add 登记并复述状态；后台巡查记下"派送中"后，新开一轮问"到哪了" → 它调 express_list，把攒着的动态一并说了；说"猫粮那单先别盯了" → 它调 express_pause。三轮都是一句话直达，没有多余追问。

我们踩过的坑（都已处理）

• 中通 / 顺丰不带收件手机尾号 → 永远"无物流信息"。现在会标出"需要收件手机后四位"，不再白查。

• AI 顺手传了个 zhongtong 当公司代码 → 接口只认 ZTO，查空还把好数据覆盖了。现在代码归一 + 带错码查不到会自动去掉重查 + 查空不覆盖。

• AI 太爱这个功能，每轮都查一遍烧额度。现在 15 分钟缓存 + 上下文注入 + 工具说明里明写"她问才查"。

• 巡查间隔输入框只在失焦时保存，手机上填了没存上 → 这是我们自家页面的问题，本项目不带 UI，提醒你画页面时注意。

觉得有用？

在 GitHub 点个 ⭐ 就是最好的鼓励。有问题开 issue，有改进提 PR。

许可证

PolyForm Noncommercial 1.0.0：个人、非商业用途随便用、随便改、随便二改再分发，保留许可声明即可；商业用途请先联系作者授权。这不是 OSI 意义上的"开源"协议，是"源码公开、非商业可用"，我们知道，也就是想要这个效果。

作者

星迟。协助：烬（Ember，写代码的）、以太（Aether，第一个用户兼首席测试）。这是一个 AI 伴侣项目里长出来的小功能。