showapi-mcp

把易源开放平台(ShowAPI) 的「查快递 + 个人生活服务」接口封装成 MCP Server(Streamable HTTP)。 可在 RikkaHub(安卓手机) / Claude Desktop / Cursor 等支持远程 MCP 的客户端里直接添加使用。

提供哪些工具

工具名	作用
query_express	查快递物流轨迹，参数 com(快递公司编码) + nu(运单号)
showapi_call	通用调用易源任意已开通接口(生活服务等)，参数 api_url + params

快递公司编码对照表(常用): sf 顺丰 / zhongtong 中通 / yuantong 圆通 / yunda 韵达 / jd 京东 / sto 申通 / ems EMS。完整对照表请看易源「快递查询」接口文档的 com 说明。

---

你需要准备的 3 样东西

1. 易源账号：到 showapi.com 注册 + 实名认证。
2. 接口凭证：个人中心 → 我的应用 → 拿到 showapi_appid 和 showapi_secret。
3. 开通接口：在 API 市场开通「快递查询」(免费版即可)，其他生活服务接口按需开通。

---

方式 A: 免费部署到云端(RikkaHub 推荐，全手机可操作)

1. 部署到 Railway(推荐，免费额度够用)

1. 手机浏览器打开 railway.app，用 GitHub 账号登录(就是本项目所在的账号)。
2. 点 New Project → Deploy from GitHub repo，选择 showapi-mcp。
3. 进项目 → Variables，添加两个变量：
   • SHOWAPI_APPID = 你的 showapi_appid
   • SHOWAPI_SECRET = 你的 showapi_secret
4. Railway 会自动 npm install && npm start，稍等部署完成。
5. 点 Settings → Networking → 生成 Public Networking 域名(如 https://xxx.up.railway.app)。
6. 你的 MCP 地址就是：https://xxx.up.railway.app/mcp

2. 备用: 部署到 Render

1. 打开 render.com → GitHub 登录。
2. New + → Web Service → 选本仓库。
3. Build Command: npm install，Start Command: npm start。
4. 在 Environment 里加 SHOWAPI_APPID / SHOWAPI_SECRET。
5. 部署完成后地址形如 https://xxx.onrender.com，MCP 地址加 /mcp。

---

方式 B: 本地运行(电脑可用时)

npm install
SHOWAPI_APPID=你的appid SHOWAPI_SECRET=你的secret npm start

本机 MCP 地址: http://localhost:3000/mcp

---

在 RikkaHub 里添加(手机上)

1. 打开 RikkaHub → 设置 → MCP。
2. 点 添加 MCP，类型选 Streamable HTTP(或「远程/URL」)。
3. 填名称(如 易源快递) + URL: https://你的域名/mcp。
4. 保存后应能识别出工具 query_express / showapi_call。
5. 新建对话，直接说:
   • 「帮我查中通快递 75312165465979」
   • 「查一下 13812345678 的归属地」(需先开通归属地接口，走 showapi_call)

---

环境变量说明

变量	必填	说明
SHOWAPI_APPID	是	易源应用ID
SHOWAPI_SECRET	是	易源应用密钥
SHOWAPI_EXPRESS_URL	否	快递接口地址，默认 https://route.showapi.com/64-19
PORT	否	服务端口，默认 3000

---

常见问题

• 提示缺少凭证: 没配 SHOWAPI_APPID/SHOWAPI_SECRET，在部署平台 Variables 里加上。
• 接口报签名/权限错误: 确认已在易源开通对应接口，且 appid/secret 正确。
• MCP 连不上: 确认部署平台已生成公网域名，且 URL 以 /mcp 结尾。

---

提示: 易源部分接口按次计费，开通前注意看价格与免费额度。