Xiaohongshu MCP Python

🚀 小红书MCP Python版本

🐍 这是一个基于Model Context Protocol的小红书自动化内容发布工具，借助Python实现小红书操作自动化，为AI客户端赋予强大的小红书内容管理能力。

🚀 快速开始

📋 环境要求

• Python 3.8 或更高版本
• uv 包管理器
• 支持的操作系统：Linux, macOS, Windows

🔧 安装步骤

1. 克隆项目

   git clone https://github.com/your-username/xiaohongshu-mcp-python.git
   cd xiaohongshu-mcp-python
   

2. 安装 uv 包管理器

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

3. 配置国内镜像源（可选）

   export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
   

4. 安装依赖

   uv sync
   

5. 安装 Playwright 浏览器

   uv run playwright install chromium
   

⚙️ 环境配置

项目支持开发环境和生产环境两种模式，可以通过环境变量或 .env 文件进行配置。

📋 环境模式说明

🔧 配置方式

方式一：使用 .env 文件（推荐）

1. 复制示例配置文件：

   cp .env.example .env
   

2. 编辑 .env 文件：

   # ============ 环境配置 ============
   # 可选值: development, production
   # development: 开发环境（有头浏览器、DEBUG日志）
   # production: 生产环境（无头浏览器、INFO日志）
   ENV=development
   
   # ============ 浏览器配置 ============
   # 是否使用无头浏览器模式
   # true: 无头模式（不显示浏览器窗口）
   # false: 有头模式（显示浏览器窗口）
   # 如果未设置，会根据 ENV 自动决定（开发环境=有头，生产环境=无头）
   # BROWSER_HEADLESS=false
   
   # ============ 日志配置 ============
   # 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL
   # 开发环境默认: DEBUG
   # 生产环境默认: INFO
   # LOG_LEVEL=DEBUG
   
   # 日志文件路径（可选，如果设置则日志会写入文件）
   # LOG_FILE=logs/xiaohongshu-mcp.log
   
   # ============ 服务器配置 ============
   # 服务器监听地址
   SERVER_HOST=127.0.0.1
   
   # 服务器端口
   SERVER_PORT=8000
   
   # ============ 用户配置 ============
   # 默认用户名
   GLOBAL_USER=luyike
   
   # ============ 超时配置 ============
   # 页面加载超时时间（毫秒）
   PAGE_LOAD_TIMEOUT=60000
   
   # 元素等待超时时间（毫秒）
   ELEMENT_TIMEOUT=30000
   

方式二：使用环境变量

# 开发环境
export ENV=development
export BROWSER_HEADLESS=false
export LOG_LEVEL=DEBUG

# 生产环境
export ENV=production
export BROWSER_HEADLESS=true
export LOG_LEVEL=INFO

方式三：命令行参数（优先级最高）

# 开发模式（默认）
uv run python -m xiaohongshu_mcp_python.main

# 生产模式
uv run python -m xiaohongshu_mcp_python.main --env production

# 开发模式但使用无头浏览器
uv run python -m xiaohongshu_mcp_python.main --env development --headless

# 生产模式但使用有头浏览器（调试用）
uv run python -m xiaohongshu_mcp_python.main --env production --no-headless

# 自定义日志级别
uv run python -m xiaohongshu_mcp_python.main --env development --log-level DEBUG

# 指定日志文件
uv run python -m xiaohongshu_mcp_python.main --log-file logs/app.log

🎛️ 可用配置项

📝 日志系统

日志系统支持以下特性：

• 控制台输出：默认输出到控制台，支持彩色显示
• 文件输出：可通过 LOG_FILE 配置同时写入文件
• 日志轮转：文件日志自动轮转（10MB）
• 日志保留：保留最近 7 天的日志
• 自动压缩：旧日志自动压缩为 zip 格式

日志格式：

{time:YYYY-MM-DD HH:mm:ss} | {level:<8} | {name}:{function}:{line} - {message}

🎯 启动服务

# 开发模式启动（默认）
uv run python -m xiaohongshu_mcp_python.main

# 生产模式启动
uv run python -m xiaohongshu_mcp_python.main --env production

# 查看帮助信息
uv run python -m xiaohongshu_mcp_python.main --help

启动后，服务将在 http://localhost:8000（或配置的端口）启动。

启动时会显示环境配置信息：

============================================================
小红书 MCP 服务器启动
运行环境: 开发环境 (development)
浏览器模式: 有头模式
日志级别: DEBUG
服务器地址: http://127.0.0.1:8000
默认用户: luyike
============================================================

✨ 主要特性

• 🚀 现代 Python 架构：基于 Python 3.8+ 和异步编程
• 🎯 MCP 协议支持：完整实现 Model Context Protocol 规范
• 🌐 Playwright 驱动：使用 Playwright 替代 Selenium，性能更优
• 📦 uv 包管理：采用现代 Python 包管理工具 uv
• 🔧 环境配置：支持开发/生产环境切换，.env 文件配置管理
• 📊 日志系统：支持控制台和文件双输出，自动轮转和压缩
• 🛡️ 类型安全：完整的类型注解支持

🎯 主要功能

📝 内容发布功能

🔍 内容管理功能

💻 使用示例

1️⃣ 登录小红书

首次使用需要登录小红书账户：

# 使用登录工具
uv run python -m src.xiaohongshu_mcp_python.login

2️⃣ 验证 MCP 连接

使用 MCP Inspector 验证连接：

npx @modelcontextprotocol/inspector

在浏览器中访问 http://localhost:18060/mcp 进行连接测试。

3️⃣ 发布内容示例

基础用法

# 发布图文内容：
{
  "tool": "publish_content",
  "parameters": {
    "title": "春日美景",
    "content": "分享今天拍摄的美丽春景，希望大家喜欢！",
    "images": [
      "/path/to/spring1.jpg",
      "/path/to/spring2.jpg"
    ],
    "tags": ["春天", "摄影", "美景"]
  }
}

🔌 MCP 客户端接入

Claude Code CLI

# 添加 MCP 服务
claude mcp add --transport http xiaohongshu-mcp-python http://localhost:18060/mcp

# 验证连接
claude mcp list

Cursor IDE

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "xiaohongshu-mcp-python": {
      "url": "http://localhost:18060/mcp",
      "description": "小红书 Python MCP 服务"
    }
  }
}

VSCode

在项目根目录创建 .vscode/mcp.json：

{
  "servers": {
    "xiaohongshu-mcp-python": {
      "url": "http://localhost:18060/mcp",
      "type": "http"
    }
  }
}

📚 详细文档

🛠️ 开发指南

📁 项目结构

xiaohongshu-mcp-python/
├── src/
│   └── xiaohongshu_mcp_python/
│       ├── __init__.py
│       ├── main.py              # 主程序入口
│       ├── mcp_server.py        # MCP 服务器实现
│       ├── xiaohongshu/         # 小红书操作模块
│       ├── utils/               # 工具函数
│       └── config/              # 配置管理
├── tests/                       # 测试文件
├── docs/                        # 文档
├── pyproject.toml              # 项目配置
├── .env.example                # 环境变量示例（开发/生产环境配置）
├── .env                        # 环境变量文件（需自行创建，已加入 .gitignore）
└── README.md

🧪 运行测试

# 运行所有测试
uv run pytest

# 运行特定测试
uv run pytest tests/test_mcp_server.py

# 生成覆盖率报告
uv run pytest --cov=src

🔍 代码质量检查

# 代码格式化
uv run black src tests

# 类型检查
uv run mypy src

# 代码风格检查
uv run flake8 src tests

🔧 可用 MCP 工具

📝 工具详细说明

xiaohongshu_publish_video - 视频发布工具

发布视频内容到小红书平台。

参数说明：

• title (必需): 视频标题，最多20个中文字或英文单词
• content (必需): 视频描述内容，不包含以#开头的标签内容
• video (必需): 视频文件路径，支持本地视频文件绝对路径
• tags (可选): 话题标签列表，如 ["美食", "旅行", "生活"]
• username (可选): 用户名，如果不提供则使用全局用户

使用示例：

# 通过 MCP 客户端调用
result = await xiaohongshu_publish_video(
    title="我的旅行视频",
    content="分享一段美好的旅行时光",
    video="/path/to/my_video.mp4",
    tags=["旅行", "生活", "美好时光"]
)

返回结果：

{
    "success": true,
    "message": "视频发布完成",
    "result": {
        "note_id": "视频笔记ID",
        "success": true
    }
}

⚠️ 注意事项

⚠️ 重要提示

• 同一账户不要在多个浏览器端同时登录
• 定期检查登录状态，及时处理 Cookie 过期
• 建议使用专门的小红书账户进行自动化操作
• 标题不超过 20 个字符
• 每日发布量建议控制在合理范围内
• 图片格式：JPG, PNG, GIF, WebP
• 视频格式：MP4, MOV, AVI（建议不超过 1GB）
• 本项目仅供学习和研究使用，请遵守小红书平台规则和相关法律法规。使用本工具产生的任何后果由使用者自行承担。

💡 使用建议

• 开发环境（development）：使用有头浏览器，方便调试和观察；使用 DEBUG 级别日志，查看详细执行过程；适合本地开发和问题排查。
• 生产环境（production）：使用无头浏览器，节省资源；使用 INFO 级别日志，减少日志量；适合服务器部署和自动化运行。
• 环境切换建议：

# 本地开发
ENV=development python -m xiaohongshu_mcp_python.main

# 服务器部署
ENV=production python -m xiaohongshu_mcp_python.main

# 或者使用 .env 文件
# 开发时：.env 中设置 ENV=development
# 生产时：.env 中设置 ENV=production

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

• 感谢 Model Context Protocol 提供的协议标准
• 感谢 Playwright 提供的浏览器自动化工具
• 感谢 uv 提供的现代 Python 包管理工具

⭐ 如果这个项目对你有帮助，请给它一个 Star！