Xiaohongshu MCP Python

# MCP 协议使用指南 ## 概述 本项目现在支持完整的 MCP (Model Context Protocol) 协议,可以通过以下方式使用: 1. **HTTP REST API** - 直接调用 HTTP 接口 2. **MCP Stdio** - 通过 stdio 协议连接 (推荐用于 Claude Desktop) 3. **MCP HTTP** - 通过 HTTP 协议连接 (推荐用于 Gemini CLI) 4. **MCP SSE** - 通过 Server-Sent Events 连接 ## 🎯 MCP 工具列表 项目提供 **13 个 MCP 工具**: | 工具名称 | 功能描述 | 参数 | |---------|---------|------| | `check_login_status` | 检查登录状态 | 无 | | `get_login_qrcode` | 获取登录二维码 | 无 | | `delete_cookies` | 删除 cookies | 无 | | `list_feeds` | 获取 Feed 列表 | 无 | | `search_feeds` | 搜索内容 | keyword, filters | | `get_feed_detail` | 获取 Feed 详情 | feed_id, xsec_token, load_all_comments | | `post_comment_to_feed` | 发表评论 | feed_id, xsec_token, content | | `reply_comment_in_feed` | 回复评论 | feed_id, xsec_token, comment_id, content | | `like_feed` | 点赞/取消点赞 | feed_id, xsec_token, action | | `favorite_feed` | 收藏/取消收藏 | feed_id, xsec_token, action | | `user_profile` | 获取用户主页 | user_id, xsec_token | | `publish_content` | 发布图文内容 | title, content, images, tags | | `publish_with_video` | 发布视频内容 | title, content, video_path, cover_path, tags | ## 📋 使用方式 ### 方式 1: HTTP REST API **启动服务**: ```bash python main.py ``` **调用示例**: ```bash # 检查登录状态 curl http://localhost:18060/api/v1/login/status # 发布内容 curl -X POST http://localhost:18060/api/v1/publish \ -H "Content-Type: application/json" \ -d '{ "title": "测试标题", "content": "测试内容", "images": ["/path/to/image.jpg"], "tags": ["标签1", "标签2"] }' ``` **API 文档**: http://localhost:18060/docs ### 方式 2: MCP Stdio (推荐用于 Claude Desktop) **1. 配置 Claude Desktop** 编辑 Claude Desktop 配置文件: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` 添加以下配置: ```json { "mcpServers": { "xiaohongshu": { "command": "python", "args": [ "/Users/xjp/Documents/project/xiaohongshu/xiaohongshu-python/mcp_stdio.py" ], "env": { "PYTHONPATH": "/Users/xjp/Documents/project/xiaohongshu/xiaohongshu-python", "HEADLESS": "true" } } } } ``` **注意**: 请将路径替换为你的实际项目路径。 **2. 重启 Claude Desktop** 配置完成后,重启 Claude Desktop,即可在对话中使用小红书工具。 **3. 使用示例** 在 Claude Desktop 中: ``` 请帮我检查小红书登录状态 请帮我发布一条小红书内容,标题是"测试",内容是"这是测试内容" ``` ### 方式 3: MCP HTTP (推荐用于 Gemini CLI) **1. 启动 HTTP 服务器**: ```bash python main.py ``` **2. 配置 Gemini CLI**: 在 Gemini CLI 配置文件中添加: ```json { "mcpServers": { "xiaohongshu": { "url": "http://localhost:18060/mcp", "transport": "http" } } } ``` **3. 测试连接**: ```bash curl -X POST http://localhost:18060/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' ``` **4. 使用示例**: 在 Gemini CLI 中: ``` 请帮我检查小红书登录状态 请帮我发布一条小红书内容 ``` **详细配置**: 查看 [Gemini CLI 配置指南](GEMINI_CLI_GUIDE.md) ### 方式 4: MCP SSE **1. 启动 HTTP 服务器**: ```bash python main.py ``` **2. 配置 MCP 客户端**: ```json { "mcpServers": { "xiaohongshu": { "url": "http://localhost:18060/sse", "transport": "sse" } } } ``` **3. 连接到 SSE 端点**: ``` GET http://localhost:18060/sse ``` ## 🔧 配置说明 ### 环境变量 在 `.env` 文件中配置: ```bash # 服务器配置 HOST=0.0.0.0 PORT=18060 # 浏览器配置 HEADLESS=true # MCP 模式建议使用 headless BROWSER_BIN_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome # 反检测配置 ENABLE_STEALTH=true MIN_ACTION_DELAY=2000 MAX_ACTION_DELAY=5000 DAILY_PUBLISH_LIMIT=10 # Cookie 配置 COOKIES_PATH=./data/cookies.json # 日志配置 LOG_LEVEL=INFO ``` ### MCP Stdio 模式特殊配置 在 stdio 模式下: - 日志只输出到文件 (`logs/mcp_stdio_*.log`) - 不输出到控制台,避免干扰 stdio 通信 - 建议使用 `HEADLESS=true` ## 📝 使用示例 ### 示例 1: 检查登录状态 **HTTP API**: ```bash curl http://localhost:18060/api/v1/login/status ``` **MCP (在 Claude Desktop 中)**: ``` 请检查小红书登录状态 ``` ### 示例 2: 发布内容 **HTTP API**: ```bash curl -X POST http://localhost:18060/api/v1/publish \ -H "Content-Type: application/json" \ -d '{ "title": "美食分享", "content": "今天做了好吃的蛋糕", "images": ["/path/to/cake.jpg"], "tags": ["美食", "烘焙", "蛋糕"] }' ``` **MCP (在 Claude Desktop 中)**: ``` 请帮我发布一条小红书内容: 标题: 美食分享 内容: 今天做了好吃的蛋糕 图片: /path/to/cake.jpg 标签: 美食, 烘焙, 蛋糕 ``` ### 示例 3: 搜索内容 **HTTP API**: ```bash curl -X POST http://localhost:18060/api/v1/search \ -H "Content-Type: application/json" \ -d '{ "keyword": "美食", "filters": null }' ``` **MCP (在 Claude Desktop 中)**: ``` 请在小红书搜索"美食"相关内容 ``` ## 🐛 故障排除 ### 问题 1: Claude Desktop 无法连接 **检查**: 1. 配置文件路径是否正确 2. Python 路径是否正确 3. 查看日志: `logs/mcp_stdio_*.log` **解决**: ```bash # 测试 stdio 模式 python mcp_stdio.py ``` ### 问题 2: MCP 工具未注册 **检查日志**: ```bash tail -f server.log | grep MCP ``` 应该看到: ``` Registering MCP tools... All 13 MCP tools registered successfully ``` ### 问题 3: SSE 连接失败 **检查**: ```bash # 测试 SSE 端点 curl -N http://localhost:18060/sse ``` **确保**: - HTTP 服务器已启动 - 端口 18060 未被占用 ### 问题 4: 浏览器启动失败 **检查**: - Chrome 浏览器路径是否正确 - Playwright 是否已安装 **解决**: ```bash playwright install chromium playwright install-deps chromium ``` ## 📊 日志查看 ### HTTP 服务器日志 ```bash tail -f server.log ``` ### MCP Stdio 日志 ```bash tail -f logs/mcp_stdio_$(date +%Y-%m-%d).log ``` ### 查看 MCP 工具调用 ```bash tail -f server.log | grep "call_tool" ``` ## 🔐 安全注意事项 1. **Cookie 安全** - Cookie 文件包含登录凭证 - 不要提交到 Git - 定期更新 Cookie 2. **API 访问控制** - 默认监听 `0.0.0.0`,允许外部访问 - 生产环境建议改为 `127.0.0.1` - 或添加认证中间件 3. **反检测配置** - 使用合理的操作频率 - 避免短时间大量操作 - 监控账号状态 ## 📚 相关文档 - [反检测功能文档](ANTI_DETECTION.md) - [项目 README](README.md) - [API 文档](http://localhost:18060/docs) - [MCP 协议规范](https://modelcontextprotocol.io/) ## 🎉 功能特性 ### ✅ 已实现 - ✅ 13 个 MCP 工具 - ✅ HTTP REST API - ✅ MCP Stdio 协议 - ✅ MCP SSE 协议 - ✅ 完整的反检测功能 - ✅ 浏览器指纹伪装 - ✅ 人类化操作 - ✅ 操作频率限制 ### 🔨 待优化 - 🔨 MCP 工具参数验证 - 🔨 更详细的错误信息 - 🔨 工具调用日志 - 🔨 性能优化 ## 💡 最佳实践 1. **开发环境**: 使用 HTTP API,方便调试 2. **Claude Desktop**: 使用 MCP Stdio,体验最佳 3. **生产环境**: 使用 HTTP API + 认证 4. **测试**: 先用 HTTP API 测试,再用 MCP ## 🆘 获取帮助 如果遇到问题: 1. 查看日志文件 2. 检查配置文件 3. 阅读相关文档 4. 提交 Issue --- **最后更新**: 2026-01-17 **版本**: 1.0.0 **维护者**: xiaohongshu-python 项目组