shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

xiaohongshu-mcp-python

小红书Python自动化发布工具，基于MCP协议实现内容发布、搜索和管理功能

article

README

🚀 小红书MCP Python版本

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

Python Version MCP Protocol License

🚀 快速开始

📋 环境要求

  • 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 文件进行配置。

📋 环境模式说明

| 环境模式 | 浏览器模式 | 日志级别 | 调试模式 | 适用场景 | |---------|-----------|---------|---------|---------| | development (开发) | 有头模式（显示浏览器） | DEBUG | 启用 | 本地开发、调试 | | production (生产) | 无头模式（后台运行） | INFO | 禁用 | 服务器部署、生产环境 |

🔧 配置方式

方式一：使用 .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

🎛️ 可用配置项

| 配置项 | 环境变量 | 默认值 | 说明 | |--------|---------|--------|------| | 环境模式 | ENV | development | development 或 production | | 浏览器模式 | BROWSER_HEADLESS | 根据 ENV 自动 | true/false，未设置时自动决定 | | 日志级别 | LOG_LEVEL | 根据 ENV 自动 | DEBUG/INFO/WARNING/ERROR | | 日志文件 | LOG_FILE | None | 日志文件路径，如果设置则同时写入文件 | | 服务器地址 | SERVER_HOST | 127.0.0.1 | HTTP 服务器监听地址 | | 服务器端口 | SERVER_PORT | 8000 | HTTP 服务器端口 | | 默认用户 | GLOBAL_USER | luyike | 默认使用的用户名 | | 页面超时 | PAGE_LOAD_TIMEOUT | 60000 | 页面加载超时（毫秒） | | 元素超时 | ELEMENT_TIMEOUT | 30000 | 元素等待超时（毫秒） |

📝 日志系统

日志系统支持以下特性：

  • 控制台输出：默认输出到控制台，支持彩色显示
  • 文件输出：可通过 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 文件配置管理
  • 📊 日志系统：支持控制台和文件双输出，自动轮转和压缩
  • 🛡️ 类型安全：完整的类型注解支持

🎯 主要功能

📝 内容发布功能

🖼️ 图文内容发布 支持发布图文内容到小红书，包括： - 📄 标题和内容描述（标题限制20字符） - 🖼️ 多图片上传（支持本地路径和HTTP链接） - 🏷️ 标签管理 - 📊 发布状态监控

图片支持格式：

  • 本地文件路径：/path/to/image.jpg
  • HTTP/HTTPS 链接：https://example.com/image.png
  • 支持格式：JPG, PNG, GIF, WebP
🎬 视频内容发布 支持发布视频内容到小红书： - 🎥 本地视频文件上传 - 📝 视频标题和描述 - ⏱️ 自动等待视频处理完成 - 🏷️ 视频标签设置

视频支持格式：

  • 本地文件：/path/to/video.mp4
  • 支持格式：MP4, MOV, AVI
  • 文件大小：建议不超过 1GB

🔍 内容管理功能

🔐 账户管理 - 登录状态检查 - Cookie 管理 - 会话保持 - 自动重新登录
🔍 内容搜索与获取 - 关键词搜索小红书内容 - 获取首页推荐列表 - 帖子详情获取（包含互动数据） - 用户主页信息获取
💬 互动功能 - 发表评论到指定帖子 - 获取评论列表 - 互动数据统计

💻 使用示例

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_start_login_session | 启动登录会话 | 无 | username | | xiaohongshu_check_login_session | 检查登录状态 | 无 | username | | xiaohongshu_cleanup_login_session | 清理登录会话 | 无 | username | | xiaohongshu_publish_content | 发布图文内容 | title, content, images | tags, username | | xiaohongshu_publish_video | 发布视频内容 | title, content, video | tags, username | | xiaohongshu_search_feeds | 搜索小红书内容 | keyword | username | | xiaohongshu_get_feeds | 获取推荐列表 | 无 | username | | xiaohongshu_get_user_profile | 获取用户主页 | user_id | username | | xiaohongshu_get_feed_detail | 获取笔记详情 | feed_id | username |

📝 工具详细说明

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 文件。

🙏 致谢

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

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端