How xpzouying/xiaohongshu-mcp works
Project type and purpose
• This is a Go-based MCP (Model Context Protocol) service that automates interactions with the Xiaohongshu website via a headless browser.
• It exposes a JSON-RPC/HTTP interface (“MCP server”) for AI clients (Claude, Cursor, VSCode, Gemini, etc.) to call tools like check_login_status, publish_content, list_feeds, search_feeds, get_feed_detail, post_comment_to_feed.
File structure
• Top-level Go binaries:
• main.go + app_server.go + routes.go + handlers_api.go + mcp_handlers.go + service.go + middleware.go + streamable_http.go → compose the HTTP/MCP server
• cmd/login/main.go → CLI tool to perform an initial manual login in a browser window
• Domain-specific package: xiaohongshu/ → browser automation for login, feeds, publish, comments
• Utilities:
• pkg/downloader → image download & processing
• cookies/cookies.go → persistence and retrieval of session cookies
• configs/*.go → runtime configuration (headless flag, image settings, username)
• Static assets + docs + examples illustrate usage and integration.
Extract key architectural insights from README
• The service starts a headless Chrome (or non-headless when ‑headless=false) and holds cookies in local storage.
• Exposes an HTTP endpoint at localhost:18060/mcp implementing the MCP JSON-RPC API.
• AI clients register the MCP server and invoke “tools” mapped to specific handlers in mcp_handlers.go.
• Each tool handler calls into service.go, which in turn drives the xiaohongshu package that executes browser tasks to perform actions on the real website.
a. Main components
1. Clients: Claude Code CLI, Cursor, VSCode, Gemini CLI, Inspector
2. HTTP/MCP Server (main.go + HTTP router + JSON-RPC layer)
3. API Handlers (handlers_api.go → generic HTTP; mcp_handlers.go → protocol mapping)
4. Service Layer (service.go)
5. Domain/Browser Adapter (xiaohongshu/*)
6. Infrastructure: Headless Chrome / Browser driver (browser/browser.go)
7. Utilities: Cookie Store, Image Downloader, Config loader
8. External System: Xiaohongshu.com website
b. Relationships & data flow
• Client sends JSON-RPC over HTTP → HTTP/MCP Server
• Router forwards to appropriate handler → Handler calls Service Layer
• Service invokes Domain Adapter → Domain Adapter issues browser commands → Chrome navigates to Xiaohongshu → returns HTML/JSON
• Service processes the result → Handler marshals it back to JSON-RPC response → back to Client
• Cookie Store is read/written by Domain Adapter to maintain session between calls
c. Architectural patterns & principles
• Layered architecture: Presentation (HTTP/MCP & routing) → Application (Handlers) → Business (Service) → Integration (xiaohongshu adapter) → Infrastructure (Browser)
• Adapter pattern for decoupling the Service logic from the browser automation details
• Dependency injection via configs package and middleware
• Clear separation of concerns: downloader, cookies, browser, handlers
d. Key technologies & frameworks
• Go standard library for HTTP, JSON-RPC handling
• Chromedp or a custom browser driver (browser/browser.go) for headless Chrome automation
• Model Context Protocol (MCP) over HTTP
• JSON-RPC 2.0
• Go modules (go.mod)
• File-based cookie persistence
Essential details to capture
• “cmd/login” as a separate sub-flow for initial authentication
• Headless vs. non-headless mode toggle
• The six MCP tools as sub-components of mcp_handlers.go
• The cookie persistence mechanism that underpins session continuity