Xiaohongshu MCP Server | 小红书 MCP 服务器
基于 MCP 协议 和 FastAPI 的小红书 API 微服务。
功能特点
-
⚡️ 双重服务器支持:
- FastAPI RESTful API 服务器
- MCP 工具集服务器
- 同时支持 HTTP API 和 MCP 协议调用
-
🔄 统一的客户端管理:
- 自动客户端生命周期管理
- 支持多个并发客户端
- 自动清理过期客户端
-
🛡️ 健壮的错误处理:
- 统一的错误处理机制
- 详细的错误信息
- 适当的状态码
-
📦 模块化设计:
- 共享的基础组件
- 清晰的代码组织
- 易于扩展
项目结构
xhs_mcp_server/
├── app/
│ └── main.py # FastAPI 应用
├── shared/
│ ├── __init__.py
│ ├── api.py # 异步 API 客户端
│ ├── client_manager.py # 客户端管理器
│ ├── error_handler.py # 错误处理
│ └── types.py # 类型定义
├── mcp_server.py # MCP 服务器
├── requirements.txt
└── README.md
环境要求
- Python 3.10+
- 依赖包:见 requirements.txt
安装
- 克隆仓库:
git clone <repository-url>
cd xhs_mcp_server
- 安装依赖:
pip install -r requirements.txt
使用方式
启动 FastAPI 服务器
uvicorn app.main:app --host 0.0.0.0 --port 8000
API 文档可访问:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
启动 MCP 服务器
python mcp_server.py
MCP 服务器将通过标准输入/输出进行通信。
API 端点
客户端管理
POST /clients- 创建新客户端GET /clients- 列出所有客户端DELETE /clients/{client_id}- 删除客户端
笔记操作
POST /clients/{client_id}/note- 获取笔记详情POST /clients/{client_id}/note/html- 从 HTML 获取笔记详情
搜索功能
POST /clients/{client_id}/search/notes- 搜索笔记POST /clients/{client_id}/search/users- 搜索用户
用户操作
POST /clients/{client_id}/user/info- 获取用户信息POST /clients/{client_id}/user/notes- 获取用户笔记
Feed 功能
GET /clients/{client_id}/feed/categories- 获取推荐流分类GET /clients/{client_id}/feed/{feed_type}- 获取推荐流内容
MCP 工具集
基础工具
create_xhs_client- 创建客户端实例get_xhs_note- 获取笔记详情get_xhs_note_html- 从 HTML 获取笔记
搜索工具
search_xhs_notes- 搜索笔记search_xhs_users- 搜索用户
用户工具
get_xhs_user_info- 获取用户信息get_xhs_user_notes- 获取用户笔记
Feed 工具
get_xhs_feed_categories- 获取推荐流分类get_xhs_feed- 获取推荐流内容
错误处理
服务器使用统一的错误处理机制:
- HTTP 状态码适当
- 详细的错误信息
- 错误类型标识
- 时间戳
- 堆栈跟踪(开发模式)
错误响应格式:
{
"status": "error",
"error": {
"error_type": "ErrorTypeName",
"error": "错误描述",
"detail": "详细信息",
"status_code": 400,
"timestamp": "2024-04-25T14:23:39"
}
}
许可证
本项目仅供学习和研究使用。使用本项目时请遵守相关法律法规和平台规则。
Metadata
Release files for iflow-mcp_xhs-mcp-agent 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_xhs_mcp_agent-0.1.0.tar.gz | 19.1 kB | Without provenance | Details for iflow_mcp_xhs_mcp_agent-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_xhs_mcp_agent-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_xhs_mcp_agent-0.1.0-py3-none-any.whl |
Total release size: 41.5 kB
Release files / iflow_mcp_xhs_mcp_agent-0.1.0.tar.gz
| Download URL | iflow_mcp_xhs_mcp_agent-0.1.0.tar.gz |
|---|---|
| Size | 19.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f6bfad4e671fcbc0e585d216298c7b6229735d85a3cced6425d910cbbb501bfa
|
|
BLAKE2b-256 checksum How to use checksums |
fe9582540f5b854ff75b229371c13163832c406753019bc37511e318da74e1c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Release files / iflow_mcp_xhs_mcp_agent-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_xhs_mcp_agent-0.1.0-py3-none-any.whl |
|---|---|
| Size | 22.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e894d7b4f6480b88064cd22f00adb2e5bcd2b0f381be9e34cd7e8105861ef17b
|
|
BLAKE2b-256 checksum How to use checksums |
5bf32c81dbbe68e3ff30669f0b86ac2aacb43e4abdd044b2a6706760425ca5f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Security for iflow-mcp_xhs-mcp-agent 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.