xhs

xhs-mcp provides a single command line entry point for managing a MCP server tailored for Xiaohongshu (xiaohongshu.com). The server supports authentication flows (login/logout/status), content publishing (image and video), discovery and search, user notes management, comments, and automated validation scripts. The included tooling is designed to drive Puppeteer-based automation in headless mode, with options to run the MCP server in stdio (default) or HTTP mode for remote access. You can run the MCP CLI via npx xhs-mcp mcp to start the stdio transport, or run npx xhs-mcp mcp --mode http to expose an HTTP/SSE API surface for programmatic control and integration with clients.

Prerequisites:

• Node.js and npm installed on your system
• Basic familiarity with using npx to run CLI commands

Step-by-step installation:

1. Install the package (recommended via npx without global install):

   • npx xhs-mcp mcp

2. If you want to install locally for development, clone the repository and install dependencies:

   • git clone <repo-url>
   • cd xhs-mcp
   • npm install

3. Ensure Puppeteer dependencies are handled by the CLI as needed (the CLI can auto-install Chromium when you first run the mcp command):

   • npx xhs-mcp mcp

4. (Optional) Start the HTTP mode MCP server:

   • npx xhs-mcp mcp --mode http --port 3000

Note: The first run may prompt to install browser dependencies for Puppeteer; you can also pre-install Chromium by running:

• npx xhs-mcp browser
• or
• npx puppeteer browsers install chrome

Tips and common considerations:

• Publishing images supports both local file paths and image URLs; image URL downloads are cached to ./temp_images/
• Video publishing accepts common formats and has file size guidance; ensure you respect per-post limits (image counts, title length, etc.)
• For HTTP mode, you can access the MCP via /mcp (Streamable HTTP) and /sse or /messages (SSE) with health checks at /health
• Enable verbose debug logs by setting XHS_ENABLE_LOGGING=true in the environment when starting the MCP
• The MCP CLI exposes a suite of tools under the xhs-mcp namespace (auth, feeds, search, user notes, publish, etc.)
• When running in stdio mode, the client can be configured via .cursor/mcp.json to automate connections; HTTP mode supports direct URL connections as an alternative
• If running multiple instances or using the same account, avoid simultaneous multi-device logins for the same account to prevent conflicts