xiaohongshu-mcp

Exposes Xiaohongshu social platform capabilities as a set of 13 standardized MCP tools consumable by AI clients (Claude, Cursor, Gemini CLI, Cline, VSCode). The service implements the Model Context Protocol specification on a /mcp endpoint with streamable HTTP transport, translating MCP tool calls into internal service method invocations. Each tool is registered in mcp_server.go with JSON schema definitions and dispatched through mcp_handlers.go to the underlying XiaohongshuService layer.

Implements a two-phase authentication system: xiaohongshu-login binary handles interactive QR code scanning via headless Chrome, persisting authenticated session cookies to cookies.json; the main xiaohongshu-mcp service reads these cookies on startup and injects them into every subsequent browser session opened via go-rod/rod. This approach bypasses the need for API credentials by reusing the user's authenticated browser context across all platform operations.

Manages headless Chrome browser instances through go-rod/rod, implementing session pooling to reuse browser contexts across multiple operations. The service opens a browser instance on startup, injects authenticated cookies into each session, and reuses the browser for subsequent tool invocations. Browser lifecycle is tied to the service lifecycle — the browser is closed when the service shuts down. This approach reduces startup latency compared to opening a new browser for each operation.

Extracts post metadata, user information, and engagement metrics by parsing the Xiaohongshu DOM through go-rod/rod's element selection and text extraction APIs. The service uses CSS selectors and XPath queries to locate elements, extract text content, and construct structured data objects. This approach enables operation without reverse-engineering proprietary APIs, but is brittle to HTML structure changes.

Implements consistent error handling and response serialization across MCP and REST interfaces. The service layer returns structured error objects with error codes, messages, and optional context; mcp_handlers.go and handlers_api.go translate these into protocol-specific responses (MCP error format or HTTP status codes). This design ensures that clients receive consistent error information regardless of which interface they use.

Implements a stateless HTTP server (using Gin framework) where each MCP or REST request opens a fresh browser page/tab within the pooled browser instance, executes the operation, and closes the page. This approach isolates state between requests, preventing cross-request contamination while reusing the browser instance for performance. The server maintains no per-request state — all context is passed through request parameters.

Provides two distinct publishing tools: publish_content for text-based posts with optional image attachments, and publish_with_video for video content. Both tools operate through browser automation, constructing the Xiaohongshu post creation form via DOM manipulation and submitting it through the live web interface. The service handles image/video file uploads, caption composition, and hashtag injection before form submission.

Implements get_feed tool that retrieves the authenticated user's Xiaohongshu feed with cursor-based pagination. The service navigates the feed DOM, extracts post metadata (title, author, engagement metrics, timestamps), and returns paginated results. Cursor tokens encode the position in the feed, enabling clients to request subsequent pages without re-fetching earlier content.

Implements search_posts tool that executes full-text search queries against Xiaohongshu's search index via the web interface. The service submits search queries through the browser, parses ranked search results from the DOM, and returns posts sorted by relevance. Search results include post metadata, author info, and engagement metrics extracted from the search result page.

Provides tools for user engagement: like_post, comment_on_post, and follow_user. Each tool operates through browser automation, simulating user interactions (clicking like buttons, submitting comment forms, following profiles) via DOM manipulation. The service handles engagement state tracking to prevent duplicate actions and returns confirmation of the engagement action.

Implements check_login_status tool that validates the current Xiaohongshu session by attempting to access a protected resource (e.g., user profile page) through the browser. The service returns the authentication status, user ID, and username if logged in, or an error if the session is invalid or expired. This tool enables clients to verify session health before executing other operations.

Implements get_login_qrcode tool that generates a fresh Xiaohongshu login QR code by opening the login page in a headless browser and extracting the QR code image. The service returns the QR code as a base64-encoded image or file path, enabling operators or AI clients to display it for scanning. This tool is typically used during initial setup or when re-authentication is required.

Implements delete_cookies tool that clears the stored Xiaohongshu session cookies from cookies.json, effectively logging out the authenticated user. This tool is destructive and irreversible — after deletion, the service cannot authenticate with Xiaohongshu until new cookies are obtained via xiaohongshu-login. The tool is useful for cleanup, security, or switching to a different user account.

Implements a dual-interface architecture where both MCP (/mcp endpoint) and REST API (/api/v1/... endpoints) dispatch to the same underlying XiaohongshuService methods. The service layer (service.go) contains all business logic, while mcp_handlers.go and handlers_api.go translate protocol-specific requests into service method calls. This design eliminates code duplication and ensures feature parity between interfaces.