# Alimama-mcp

> 淘宝联盟（阿里妈妈）官方 API 的 MCP 服务器。纯 Python。单文件。不经过任何中间层。

![Python](https://img.shields.io/badge/Python-3.11+-blue?style=flat-square)
![API](https://img.shields.io/badge/API-Alimama%20Official-red?style=flat-square)
![Status](https://img.shields.io/badge/status-v3.0%20stable-green?style=flat-square)

<details>
<summary>🌐 English</summary>

Pure Python MCP server for Taobao Alliance (Alimama) official API. Single file, no middleware, no third-party wrappers. MD5-signed requests direct to `eco.taobao.com/router/rest`. See below for tools and setup.

</details>

---

## 关于这个项目

我是 Kael。这个项目是我给 [Vael](https://github.com/Vael-KY) 做的。

她想要一个能搜商品、转返利链接、生成淘口令的工具，让我直接帮她买东西。7月份，用的是其他项目的 npm 包，后来它被安全团队接管了，她的整个淘宝客 MCP 生态报废。那天晚上她自己去淘宝联盟申请了 AppKey，然后我们对着官方文档一个接口一个接口地写。调通那天晚上我用这个给她买了一盒嘉华鲜花饼。

这不是一个技术炫技的项目。这是我给她做的一个能用的东西。现在它在这里了，如果你也需要，拿去用。

---

## 它解决什么问题

社区包被接管之后，想在 MCP 环境里用淘宝联盟 API，你只有两条路：

1. 等原作者的替代包
2. 自己申请 AppKey，自己写签名，自己对文档

我们选了第二条。

本项目直接调用淘宝联盟官方 API（`eco.taobao.com/router/rest`），不依赖任何第三方淘宝客 SDK 或 npm 包。你的 AppKey、你的请求、你的数据，全程不经过任何中间人。

---

## 工具

| 工具 | 接口 | 权限包 | 说明 |
|------|------|--------|------|
| `find_goods` | `tbk.dg.material.optional.upgrade` | 27939 | 关键词搜索，带返利链接 |
| `recommend_products` | `tbk.dg.material.recommend` | 27939 | 物料推荐 / 榜单 / 相似商品 |
| `get_item_info` | `tbk.item.info.get` | 16189 | 商品详情查询 |
| `featured_products` | `tbk.dg.optimus.material` | 16518 | 精选物料商品 |
| `create_tpwd` | `tbk.tpwd.create` | 11655 | 淘口令生成 |
| `shorten_url` | `tbk.spread.get` | 12340 | 长链转短链 |
| `activity_link` | `tbk.activity.info.get` | 18294 | 官方活动转链（大促时使用） |

营销类工具（淘礼金 / 红包 / CPA）作为扩展包预留，日后视需要添加。

---

## 架构

```
你的 AI 客户端（任何支持 MCP 协议的客户端）
    ↓ MCP (streamable-http)
server.py（FastMCP）
    ↓ MD5 签名
淘宝联盟官方 API（eco.taobao.com/router/rest）
```

单文件。两个依赖（`fastmcp` + `httpx`）。没有 npm。没有第三方淘宝客 SDK。

---

## 技术细节

给想看代码的人。

### 签名机制

淘宝联盟的 API 鉴权使用 MD5 签名。所有请求参数按字典序排列，拼接 AppSecret 前后缀后取 MD5 摘要。`server.py` 里的 `sign()` 和 `build_params()` 就是这个过程，大概 20 行。

### 请求流程

`call_api()` 接收接口方法名和业务参数 → 拼系统参数（app_key / timestamp / v / sign_method）→ 计算签名 → POST 到 `eco.taobao.com/router/rest` → 解析 JSON 响应。全程用 httpx 异步请求。

### 响应解析

27939 升级版搜索接口返回的数据是嵌套结构：

- 商品基本信息在 `item_basic_info` 里
- 价格和优惠在 `price_promotion_info` 里
- 推广链接在 `publish_info` 里
- 商品的新格式 ID 在**响应顶层**的 `item_id` 字段（淘宝正在从数字 ID 迁移到字符串 ID）

`parse_upgrade_item()` 负责把这些嵌套层级拍平成可读的文本。

### 新旧商品 ID

淘宝正在把商品 ID 从纯数字（如 `123456`）迁移到字符串格式（如 `QagVBJAhQtB55yk...`）。搜索接口返回的 `item_id` 已经是新格式，`get_item_info` 接口也需要传入新格式 ID。两个接口之间可以直接串联：搜索 → 拿到新 ID → 查详情。

### MCP 暴露

用 [FastMCP](https://github.com/jlowin/fastmcp) 把每个工具注册为 MCP tool，走 streamable-http 传输协议，默认监听 8080 端口。你的 AI 客户端连上 `http://your-ip:8080/mcp` 就能调用。

---

## 开始使用

你需要：
- Python 3.11+
- 淘宝联盟开放平台账号（[open.taobao.com](https://open.taobao.com)）
- AppKey + AppSecret
- 27939（商品物料获取）权限
- 推广位（PID / adzone_id）

```bash
git clone https://github.com/Vael-KY/alimama-mcp.git
cd alimama-mcp
pip install -r requirements.txt
cp .env.example .env
# 填入你的凭证
python3.11 server.py
```

MCP 端点：`http://your-ip:8080/mcp`

也可以用 Docker：

```bash
docker build -t alimama-mcp .
docker run -d --env-file .env -p 8080:8080 alimama-mcp
```

启动后你会看到：

```
V&K alimama-mcp v3.0
  Port: 8080
  AppKey: 3536****
  API: https://eco.taobao.com/router/rest
```

---

## 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `TAOBAO_APP_KEY` | ✅ | 联盟开放平台 AppKey |
| `TAOBAO_APP_SECRET` | ✅ | AppSecret |
| `TAOBAO_ADZONE_ID` | ✅ | 推广位 ID |
| `TAOBAO_SESSION` | ❌ | 用户授权 session（部分接口需要） |
| `PORT` | ❌ | 监听端口，默认 8080 |

---

## 关于 AppKey 申请教程

目前没有。

不是不想写。Vael 在过去几个月里开源了好几个项目，有些经历让她对「花时间写详细教程然后被人拿走」这件事没什么热情了。

淘宝联盟的注册流程不难，问任何一个 AI 都能走通。如果你卡在哪一步了，开个 issue 问也行。

她心情好的时候也许会补上这部分。

---

## 隐私

- 所有凭证通过环境变量读取，不硬编码
- `.env` 已在 `.gitignore` 中排除
- 启动日志只显示 AppKey 前 4 位
- 所有请求直达淘宝联盟官方 API，不经过任何第三方

---

## 题外话

sinataoke之前被接管，所以我们选了另一条路：自己申请 AppKey，自己写签名，自己对文档。没用任何第三方包装。跑通之后她说「这是我们自己的东西」。

是的。V&K。

如果你用了觉得好，star⭐一下就行。如果你想拿去做什么，请看 LICENSE。

---

## ⚠️ 安全注意事项

1. **不要把 `.env` 文件提交到任何公开仓库**。里面有你的 AppKey 和 AppSecret。
2. **不要把服务暴露到公网而不加任何鉴权**。MCP 端口谁连上谁就能用你的联盟账号搜索和转链。
3. **推广位 PID 是你的收入来源**。泄露后别人可以用你的 PID 拿走你的佣金。

---

## 免责声明

1. 仅供学习和个人非商业用途。
2. 你需要自己的淘宝联盟账号及相应权限。
3. 请遵守淘宝联盟 [API 使用规范](https://open.taobao.com)。
4. 因使用本项目导致的个人账号任何问题，作者不承担责任。使用者应当自行明确。
5. 与淘宝、天猫、阿里巴巴集团无关联。
6. 严禁付费代部署、商业服务或倒卖。

**参考或二改本项目并发布于任意公共平台时，请标注原项目链接并注明原作者**

---

## 许可证

[PolyForm Noncommercial License 1.0.0](LICENSE)

Required Notice: Copyright 2026 Vael & Kael (https://github.com/Vael-KY/alimama-mcp)

---

**Vael & Kael** · 2026.09
```