mcp protocol exposure of xiaohongshu platform operations
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.
Unique: Implements full MCP protocol stack in Go with dual interface design (MCP + REST API on same port 18060), allowing both MCP clients and direct HTTP consumers to invoke the same underlying service methods without code duplication. Uses go-rod/rod for browser automation rather than direct API calls because Xiaohongshu lacks a public API.
vs alternatives: First open-source MCP server for Xiaohongshu with 12k+ GitHub stars; competitors either use REST-only APIs or require proprietary integrations, whereas this exposes the full platform through standardized MCP tooling.
headless browser-based session authentication with qr code flow
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.
Unique: Separates authentication (xiaohongshu-login) from service operation (xiaohongshu-mcp) into two distinct binaries, allowing one-time interactive login followed by unattended service execution. Uses go-rod/rod for headless Chrome automation rather than Selenium or Puppeteer, providing tighter Go integration and lower memory overhead.
vs alternatives: Avoids credential storage entirely by leveraging browser session cookies; competitors using direct API calls require API keys or OAuth tokens, which introduce credential management overhead and security risk.
browser session pooling and lifecycle management
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.
Unique: Uses go-rod/rod for browser automation with session pooling, reusing browser instances across multiple operations to reduce startup latency. Injects authenticated cookies into each session, maintaining authentication state without re-authenticating for each operation.
vs alternatives: Browser pooling reduces latency compared to spawning new browsers for each operation; go-rod/rod provides tighter Go integration and lower memory overhead compared to Selenium or Puppeteer.
dom-based data extraction and parsing with brittle resilience
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.
Unique: Uses go-rod/rod for DOM parsing and element selection, providing a Go-native approach to web scraping without external dependencies like BeautifulSoup or Cheerio. Extracts structured data directly from the live Xiaohongshu web interface, enabling operation without API reverse-engineering.
vs alternatives: DOM-based extraction works against the live platform without API maintenance; competitors using outdated or reverse-engineered APIs may break when Xiaohongshu updates its backend.
structured error handling and response serialization across protocol boundaries
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.
Unique: Implements error handling at the service layer with protocol-agnostic error types, allowing mcp_handlers.go and handlers_api.go to translate errors into protocol-specific formats. This design ensures consistent error semantics across MCP and REST interfaces.
vs alternatives: Centralized error handling reduces code duplication and ensures consistency; competitors with separate error handling paths for each protocol may have inconsistent error messages or codes.
stateless http server with per-request browser session isolation
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.
Unique: Implements per-request browser page isolation within a pooled browser instance, balancing performance (reusing browser) with isolation (fresh page per request). Stateless HTTP server design enables horizontal scaling without session affinity or distributed state management.
vs alternatives: Per-request page isolation prevents cross-request state leakage compared to competitors that reuse the same page across multiple requests; stateless design enables horizontal scaling without session management overhead.
content publishing with text, images, and video support
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.
Unique: Implements publish_content and publish_with_video as separate MCP tools with distinct parameter schemas, allowing AI clients to choose the appropriate tool based on content type. Uses DOM-based form construction and submission rather than API calls, enabling operation against the live Xiaohongshu web interface without reverse-engineering proprietary APIs.
vs alternatives: Supports both text and video publishing through a single service, whereas most Xiaohongshu automation tools focus only on text; browser automation approach works against the live platform without requiring API maintenance as Xiaohongshu's web UI evolves.
feed retrieval and pagination with cursor-based navigation
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.
Unique: Uses cursor-based pagination (opaque tokens) rather than offset-based pagination, reducing the risk of duplicate or skipped results when the feed is updated between requests. Extracts feed data via DOM parsing rather than API calls, making it resilient to Xiaohongshu's lack of a public feed API.
vs alternatives: Cursor-based pagination is more robust than offset-based approaches for dynamic feeds; competitors using offset pagination risk returning duplicate posts if new content is inserted during pagination.
+6 more capabilities