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！