Content
# XianYu MCP Server
Based on the encapsulation of `third_party/XianYuApis`, this is a XianYu MCP project that enables integrating XianYu's product, conversation, and message sending capabilities into MCP-supported clients.
## 🛡 Precautions
> [!WARNING]
> This project is an open-source project. Please use it in compliance with relevant laws and regulations and platform rules.
>
> Given the specificity of the project, the development team may stop updating or delete the project at any time.
## 📄 Usage Agreement
This project adopts the `GNU GPL v3.0` protocol.
- Allowed: Learning, modification, distribution, and re-release
- Requirements: Derivative works must continue to follow GPL v3.0 terms when distributed
- Note: Third-party dependencies or submodules are subject to their respective protocols
See detailed terms in [`LICENSE`](./LICENSE).
## ✨ Project Overview
The current repository consists of two layers:
- `third_party/XianYuApis`: XianYu underlying HTTP/WebSocket capabilities
- `.mcp/XianYuApis_MCP`: Tool encapsulation for MCP
Suitable usage scenarios:
- Directly call XianYu capabilities in MCP-supported clients like Trae, Cherry Studio, or Claude Desktop
- Integrate XianYu seller workflows into custom agents/workflow orchestration systems
- As infrastructure for subsequent automated customer service, message distribution, and store operation scripts
## 🚀 Current Capabilities
The following tools are currently available for MCP:
| Tool Name | Description |
| --- | --- |
| `validate_login` | Verify if the current Cookie is valid and attempt to obtain `accessToken` |
| `refresh_login` | Refresh the current login status |
| `get_item_detail` | Get the details of a specified product |
| `get_item_edit_detail` | Get the edit details of a specified product on the PC edit page |
| `list_my_items` | Pull the list of all products under the current account and automatically paginate |
| `downshelf_item` | Remove a specified product from the current account |
| `reshelf_item` | Re-list a specified product through the PC edit re-publishing link |
| `list_conversations` | Pull the recent conversation list |
| `list_conversation_messages` | Pull historical messages for a specified conversation |
| `send_text_message` | Actively send text messages |
| `send_image_message` | Actively send image messages |
The following capabilities have been verified:
- Can read the current login user's `userId`
- Can verify and refresh login status
- Can pull the product list of the current account
- Can obtain product details
- Can obtain product edit details
- Can perform product removal
- Can re-list products that support PC editing
## 🚧 Current Limitations
The current version prioritizes short call tools and does not yet support the following capabilities:
- Scan code login
- Resident listening to messages
- Automatic reply worker
- Independent MCP tool for media upload
- Complete publishing link for new products
The underlying `third_party/XianYuApis` has supplemented some product publishing-related primitive interfaces, such as:
- `prepublish_check`
- `preget`
- `edit_item`
- `build_reshelf_payload`
The current MCP layer only exposes `get_item_edit_detail` and `reshelf_item`, which are more frequent and directly landed.
Regarding product listing and delisting, note:
- `downshelf_item` has been verified for ordinary product removal
- `reshelf_item` essentially uses the PC "edit and re-publish" link
- Virtual products are currently subject to XianYu PC publishing control and may return `FAIL_BIZ_PC_NOT_SUPPORT_PUBLISH_OR_EDIT` when called
- Therefore, in the current repository, "virtual products cannot be re-listed on the PC through MCP/API" is a platform limitation, not a repository parameter issue
- Other physical products that support PC editing have been verified to be able to remove and re-list
If you plan to connect AI automated customer service, it is recommended to split "message listening" and "MCP short calls" into two processes and not put the resident loop directly into the MCP main process.
## 🗂️ Directory Structure
```text
xianyu-mcp-server/
├── .mcp/
│ └── XianYuApis_MCP/
│ ├── .env.example
│ ├── README.md
│ ├── pyproject.toml
│ ├── server.py
│ └── tools/
│ └── xianyu_api_tools.py
├── .trae/
│ └── mcp.json
├── third_party/
│ └── XianYuApis/
└── README.md
```
## 🧰 Environment Requirements
- Python 3.11+
- Node.js 18+
- `uv`
- Complete XianYu Cookie after login
## ⚙️ Quick Start
### 1. Pull Submodule
```bash
git submodule update --init --recursive
```
### 2. Prepare Environment Variables
```bash
cd .mcp/XianYuApis_MCP
cp .env.example .env
```
Fill in the login status:
```env
XIANYU_COOKIE=Your complete XianYu Cookie
```
Alternatively, use a file:
```env
XIANYU_COOKIE_FILE=./cookie.txt
```
Choose one between `XIANYU_COOKIE` and `XIANYU_COOKIE_FILE`.
### 3. Install Dependencies
```bash
uv sync --directory .mcp/XianYuApis_MCP
```
### 4. Start MCP Locally
Default `stdio`:
```bash
uv run --directory .mcp/XianYuApis_MCP server.py
```
HTTP mode:
```bash
uv run --directory .mcp/XianYuApis_MCP server.py --http
```
HTTP mode listens on: `http://localhost:8000/mcp`
## 🔌 Trae Integration
Create or modify `.trae/mcp.json` in the project root directory:
```json
{
"mcpServers": {
"xianyuapis": {
"command": "uv",
"args": [
"--directory",
"${workspaceFolder}/.mcp/XianYuApis_MCP",
"run",
"server.py"
]
}
}
}
```
Description:
- `xianyuapis` is just the MCP service name and can be customized
- If your Trae uses the absolute path version of `uv`, keep the Trae auto-generated path
- After configuration, reload Trae or reopen the workspace
## 🧪 Recommended Verification Process
After integration, it is recommended to verify in the following order:
1. Call `validate_login` to confirm the current Cookie is valid
2. Call `list_my_items` to confirm you can get your product list
3. Call `get_item_detail` to confirm the details interface is available
4. If store operation actions are needed, call `downshelf_item`
5. If you need to re-list a product that has been removed, call `reshelf_item`
## 💡 Usage Suggestions
- `list_my_items` `page_size` is recommended to use the default value `20`
- In certain accounts or scenarios, the server may impose stricter limits on the number of items per page. Passing a large value may return `FAIL_BIZ_FORBIDDEN`
- `server.py` will re-read `.env` for each tool call. If the MCP client caches the process or configuration, it is recommended to reload the MCP service after updating the Cookie
## ❓ Frequently Asked Questions
### 1. Trae Cannot Detect XianYu MCP
Usually due to one of the following reasons:
- No `.trae/mcp.json` in the project root directory
- `mcpServers` does not register the current service
- `command` or `args` path is incorrect
### 2. `validate_login` Returns `FAIL_SYS_USER_VALIDATE`
Usually indicates that the current Cookie has expired, is incomplete, or lacks critical fields.
Please copy the complete Cookie from a logged-in browser and update `.mcp/XianYuApis_MCP/.env`.
### 3. Why Does Modifying the Cookie Not Take Effect
The current implementation re-reads `.env` before each tool call. Usually, as long as the modification is made to:
- `.mcp/XianYuApis_MCP/.env`
- or `XIANYU_COOKIE_FILE` points to the actual file
The new value will be read automatically for the next call.
If the current MCP client caches the service process, reloading the MCP service in the client is more reliable.
### 4. `list_my_items` Reports Page or Item Limit Exceeded
Please adjust `page_size` back to the default value `20`.
Although the tool layer constrains the parameter to `1 ~ 50`, the server's actual limit for different accounts may be stricter.
### 5. Why Some Interfaces Are Not Available in MCP
`third_party/XianYuApis` is the underlying capability library, and `.mcp/XianYuApis_MCP` only encapsulates some high-frequency scenarios.
Currently, not all APIs are automatically exposed to MCP. For example, `prepublish_check`, `preget`, `edit_item`, etc. are still retained as underlying call capabilities.
### 6. Why Some Products Can Be Re-Listed While Others Cannot
The current `reshelf_item` uses the XianYu PC edit re-publishing link.
If a product is limited by the platform to "only support App publishing/editing", the interface will return:
- `FAIL_BIZ_PC_NOT_SUPPORT_PUBLISH_OR_EDIT`
Current conclusions:
- Virtual products usually hit this PC control and cannot be re-listed through the current MCP
- Physical products that support PC editing can continue to use `downshelf_item` / `reshelf_item`
## 📚 Related Documents
- MCP encapsulation description: [`./.mcp/XianYuApis_MCP/README.md`](./.mcp/XianYuApis_MCP/README.md)
- Underlying project description: [`./third_party/XianYuApis/README.md`](./third_party/XianYuApis/README.md)
- Product list interface record: [`./third_party/XianYuApis/docs/mtop_idle_web_xyh_item_list.md`](./third_party/XianYuApis/docs/mtop_idle_web_xyh_item_list.md)
- Product removal interface record: [`./third_party/XianYuApis/docs/mtop_taobao_idle_item_downshelf.md`](./third_party/XianYuApis/docs/mtop_taobao_idle_item_downshelf.md)
- Product edit details interface record: [`./third_party/XianYuApis/docs/mtop_idle_pc_idleitem_edit_detail.md`](./third_party/XianYuApis/docs/mtop_idle_pc_idleitem_edit_detail.md)
- Product re-publishing interface record: [`./third_party/XianYuApis/docs/mtop_idle_pc_idleitem_edit.md`](./third_party/XianYuApis/docs/mtop_idle_pc_idleitem_edit.md)
Connection Info
You Might Also Like
No recommendations available