Xiaohongshu MCP Python

🚀 xiaohongshu-mcp-python

🐍 The Python version of Xiaohongshu MCP - An automated content publishing tool for Xiaohongshu based on the Model Context Protocol.

🚀 Quick Start

📋 Environment Requirements

• Python 3.8 or higher
• uv package manager
• Supported operating systems: Linux, macOS, Windows

🔧 Installation Steps

1. Clone the project

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

2. Install the uv package manager

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

3. Configure the domestic mirror source (optional)

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

4. Install dependencies

   uv sync
   

5. Install the Playwright browser

   uv run playwright install chromium
   

⚙️ Environment Configuration

The project supports two modes: development environment and production environment, which can be configured through environment variables or the .env file.

📋 Environment Mode Description

🔧 Configuration Methods

Method 1: Use the .env file (recommended)

1. Copy the example configuration file:

   cp .env.example .env
   

2. Edit the .env file:

   # ============ Environment Configuration ============
   # Optional values: development, production
   # development: Development environment (headed browser, DEBUG logs)
   # production: Production environment (headless browser, INFO logs)
   ENV=development
   
   # ============ Browser Configuration ============
   # Whether to use the headless browser mode
   # true: Headless mode (do not show the browser window)
   # false: Headed mode (show the browser window)
   # If not set, it will be automatically determined according to ENV (development = headed, production = headless)
   # BROWSER_HEADLESS=false
   
   # ============ Log Configuration ============
   # Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
   # Default for development environment: DEBUG
   # Default for production environment: INFO
   # LOG_LEVEL=DEBUG
   
   # Log file path (optional, if set, logs will be written to the file)
   # LOG_FILE=logs/xiaohongshu-mcp.log
   
   # ============ Server Configuration ============
   # Server listening address
   SERVER_HOST=127.0.0.1
   
   # Server port
   SERVER_PORT=8000
   
   # ============ User Configuration ============
   # Default username
   GLOBAL_USER=luyike
   
   # ============ Timeout Configuration ============
   # Page load timeout (milliseconds)
   PAGE_LOAD_TIMEOUT=60000
   
   # Element wait timeout (milliseconds)
   ELEMENT_TIMEOUT=30000
   

Method 2: Use environment variables

# Development environment
export ENV=development
export BROWSER_HEADLESS=false
export LOG_LEVEL=DEBUG

# Production environment
export ENV=production
export BROWSER_HEADLESS=true
export LOG_LEVEL=INFO

Method 3: Use command-line parameters (highest priority)

# Development mode (default)
uv run python -m xiaohongshu_mcp_python.main

# Production mode
uv run python -m xiaohongshu_mcp_python.main --env production

# Development mode but use the headless browser
uv run python -m xiaohongshu_mcp_python.main --env development --headless

# Production mode but use the headed browser (for debugging)
uv run python -m xiaohongshu_mcp_python.main --env production --no-headless

# Customize the log level
uv run python -m xiaohongshu_mcp_python.main --env development --log-level DEBUG

# Specify the log file
uv run python -m xiaohongshu_mcp_python.main --log-file logs/app.log

🎛️ Available Configuration Items

📝 Log System

The log system supports the following features:

• Console output: Outputs to the console by default, supporting color display
• File output: Can be configured to write to a file through LOG_FILE
• Log rotation: File logs are automatically rotated (10MB)
• Log retention: Keeps the logs of the last 7 days
• Automatic compression: Old logs are automatically compressed into zip format

Log format:

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

🎯 Start the Service

# Start in development mode (default)
uv run python -m xiaohongshu_mcp_python.main

# Start in production mode
uv run python -m xiaohongshu_mcp_python.main --env production

# View help information
uv run python -m xiaohongshu_mcp_python.main --help

After starting, the service will start at http://localhost:8000 (or the configured port).

The environment configuration information will be displayed when starting:

============================================================
Xiaohongshu MCP server started
Running environment: Development environment (development)
Browser mode: Headed mode
Log level: DEBUG
Server address: http://127.0.0.1:8000
Default user: luyike
============================================================

✨ Features

xiaohongshu-mcp-python is an automated content publishing tool for Xiaohongshu developed in Python. It provides Xiaohongshu operation capabilities for AI clients through the Model Context Protocol (MCP). This project uses a modern Python technology stack, supports asynchronous operations, and provides efficient and stable Xiaohongshu content management services.

✨ Core Features

• 🚀 Modern Python architecture: Based on Python 3.8+ and asynchronous programming
• 🎯 MCP protocol support: Fully implements the Model Context Protocol specification
• 🌐 Playwright driver: Uses Playwright instead of Selenium for better performance
• 📦 uv package management: Adopts the modern Python package management tool uv
• 🔧 Environment configuration: Supports switching between development and production environments, and manages configuration through the .env file
• 📊 Logging system: Supports both console and file output, with automatic rotation and compression
• 🛡️ Type safety: Full type annotation support

🎯 Main Functions

📝 Content Publishing Function

🔍 Content Management Function

💻 Usage Examples

1️⃣ Log in to Xiaohongshu

You need to log in to your Xiaohongshu account for the first use:

# Use the login tool
uv run python -m src.xiaohongshu_mcp_python.login

2️⃣ Verify the MCP Connection

Use the MCP Inspector to verify the connection:

npx @modelcontextprotocol/inspector

Access http://localhost:18060/mcp in the browser for a connection test.

3️⃣ Example of Publishing Content

Publish image-text content:

# Call through the MCP tool
{
  "tool": "publish_content",
  "parameters": {
    "title": "Spring Scenery",
    "content": "Share the beautiful spring scenery I shot today. I hope you like it!",
    "images": [
      "/path/to/spring1.jpg",
      "/path/to/spring2.jpg"
    ],
    "tags": ["Spring", "Photography", "Beautiful Scenery"]
  }
}

📚 Documentation

🔌 MCP Client Access

Claude Code CLI

# Add the MCP service
claude mcp add --transport http xiaohongshu-mcp-python http://localhost:18060/mcp

# Verify the connection
claude mcp list

Cursor IDE

Create .cursor/mcp.json in the project root directory:

{
  "mcpServers": {
    "xiaohongshu-mcp-python": {
      "url": "http://localhost:18060/mcp",
      "description": "Xiaohongshu Python MCP service"
    }
  }
}

VSCode

Create .vscode/mcp.json in the project root directory:

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

🛠️ Development Guide

📁 Project Structure

xiaohongshu-mcp-python/
├── src/
│   └── xiaohongshu_mcp_python/
│       ├── __init__.py
│       ├── main.py              # Main program entry
│       ├── mcp_server.py        # MCP server implementation
│       ├── xiaohongshu/         # Xiaohongshu operation module
│       ├── utils/               # Utility functions
│       └── config/              # Configuration management
├── tests/                       # Test files
├── docs/                        # Documentation
├── pyproject.toml              # Project configuration
├── .env.example                # Example environment variables (development/production environment configuration)
├── .env                        # Environment variable file (need to create it yourself, added to .gitignore)
└── README.md

🧪 Run Tests

# Run all tests
uv run pytest

# Run specific tests
uv run pytest tests/test_mcp_server.py

# Generate a coverage report
uv run pytest --cov=src

🔍 Code Quality Check

# Code formatting
uv run black src tests

# Type checking
uv run mypy src

# Code style checking
uv run flake8 src tests

🔧 Available MCP Tools

📝 Detailed Tool Description

xiaohongshu_publish_video - Video Publishing Tool

Publish video content to the Xiaohongshu platform.

Parameter description:

• title (required): Video title, up to 20 Chinese characters or English words
• content (required): Video description content, excluding tags starting with #
• video (required): Video file path, supports the absolute path of local video files
• tags (optional): List of topic tags, such as ["Food", "Travel", "Life"]
• username (optional): Username, if not provided, the global user will be used

Usage example:

# Call through the MCP client
result = await xiaohongshu_publish_video(
    title="My Travel Video",
    content="Share a wonderful travel time",
    video="/path/to/my_video.mp4",
    tags=["Travel", "Life", "Wonderful Time"]
)

Return result:

{
    "success": true,
    "message": "Video published successfully",
    "result": {
        "note_id": "Video note ID",
        "success": true
    }
}

⚠️ Important Note

🔒 Account Security

• Do not log in to the same account on multiple browser clients simultaneously.
• Regularly check the login status and handle expired cookies in a timely manner.
• It is recommended to use a dedicated Xiaohongshu account for automated operations.

📊 Publishing Restrictions

• The title should not exceed 20 characters.
• It is recommended to control the daily publishing volume within a reasonable range.
• Image formats: JPG, PNG, GIF, WebP
• Video formats: MP4, MOV, AVI (it is recommended not to exceed 1GB)

🔐 Best Practices for Environment Modes

Development Environment (development)

• ✅ Use a headed browser for easy debugging and observation.
• ✅ DEBUG level logs to view the detailed execution process.
• ✅ Suitable for local development and problem troubleshooting.

Production Environment (production)

• ✅ Use a headless browser to save resources.
• ✅ INFO level logs to reduce the log volume.
• ✅ Suitable for server deployment and automated operation.

Environment Switching Suggestions

# Local development
ENV=development python -m xiaohongshu_mcp_python.main

# Server deployment
ENV=production python -m xiaohongshu_mcp_python.main

# Or use the .env file
# For development: Set ENV=development in .env
# For production: Set ENV=production in .env

🛡️ Risk Warning

This project is for learning and research purposes only. Please comply with the rules of the Xiaohongshu platform and relevant laws and regulations. The user shall bear all consequences arising from the use of this tool.

🤝 Contribution Guide

Welcome to submit Issues and Pull Requests!

1. Fork this project.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Commit your changes: git commit -m 'Add amazing feature'.
4. Push the branch: git push origin feature/amazing-feature.
5. Submit a Pull Request.

📄 License

This project is licensed under the MIT license. See the LICENSE file for details.

🙏 Acknowledgments

• Thanks to Model Context Protocol for providing the protocol standard.
• Thanks to Playwright for providing the browser automation tool.
• Thanks to uv for providing the modern Python package management tool.

⭐ If this project is helpful to you, please give it a Star!