Core Technologies Used in xiaohongshu-mcp: Go, MCP SDK, and Browser Automation

Xiaohongshu-mcp is a Go 1.24 service that combines the Gin web framework, Model Context Protocol SDK, and go-rod browser automation library to expose Xiaohongshu platform operations via a streaming HTTP API.

The xiaohongshu-mcp project provides a machine-readable interface for the Xiaohongshu (Little Red Book) social platform, enabling automated content publishing and account management. Written entirely in Go, the codebase integrates modern web protocols with headless browser automation to bridge the gap between AI agents and social media workflows. Understanding the core technologies used in xiaohongshu-mcp reveals how the project maintains reliability while interacting with a complex, JavaScript-heavy web application.

Go 1.24 Runtime and Module Architecture

The foundation of xiaohongshu-mcp is Go 1.24, declared in the module definition at go.mod (lines 1‑4). The language’s native concurrency primitives (goroutines and channels) support concurrent browser sessions and HTTP request handling without external async frameworks.

The project follows standard Go module conventions with dependencies managed through go.mod (lines 5‑12), including utility libraries for retry logic, file type detection, and error wrapping.

HTTP Routing with Gin-Gonic

For the public API layer, xiaohongshu-mcp uses Gin-Gonic (github.com/gin-gonic/gin), a high-performance HTTP web framework. The router setup in routes.go (lines 10‑38) defines endpoints for health checks and MCP streaming.

Gin handles JSON binding, middleware registration, and graceful shutdown. The middleware.go file implements global error handling and CORS policies, keeping the HTTP layer clean and consistent.

// Server bootstrap in main.go
srv := NewAppServer(xhsService)
if err := srv.Start(":8080"); err != nil {
    logrus.Fatalf("server failed: %v", err)
}

Model Context Protocol (MCP) SDK

At the heart of the service lies the Model Context Protocol (MCP) SDK (github.com/modelcontextprotocol/go-sdk/mcp). This implements the server-side MCP specification, allowing AI clients to stream requests to the /mcp endpoint.

In app_server.go (lines 11‑13), the application creates an MCP server using the SDK’s NewStreamableHTTPHandler, which manages the protocol handshake and request forwarding to internal services.

Browser Automation with go-rod

To interact with the Xiaohongshu web interface, xiaohongshu-mcp employs go-rod (github.com/go-rod/rod), a Chrome DevTools Protocol (CDP) driver, along with the stealth plugin for anti-detection. This technology stack simulates real user behavior, including login flows, image uploads, and tag selection.

The login functionality in xiaohongshu/login.go (lines 7‑34) demonstrates QR-code retrieval and session management:

// Login and obtain QR code
login := xiaohongshu.NewLogin(page)
src, needQR, err := login.FetchQrcodeImage(ctx)
if needQR {
    // Send src to client for user scanning
}

For content publishing, xiaohongshu/publish.go contains the PublishImageContent method that drives a headless Chromium instance through the complete post creation workflow:

// Publish an image post
pub := xiaohongshu.NewPublishImageAction(page)
content := xiaohongshu.PublishImageContent{
    Title:      "My Travel Diary",
    Content:    "Exploring the mountains!",
    ImagePaths: []string{"./pics/1.jpg"},
    Tags:       []string{"#travel", "#mountains"},
    IsOriginal: true,
}
if err := pub.Publish(ctx, content); err != nil {
    logrus.Errorf("publish failed: %v", err)
}

Observability and Infrastructure

The project uses logrus (github.com/sirupsen/logrus) for structured, leveled logging throughout the server and automation code, as seen in publish.go (lines 88‑90).

For resilience, the codebase integrates github.com/avast/retry-go/v4 for robust network calls and github.com/h2non/filetype for image validation before upload.

Deployment relies on Docker, with the Dockerfile (lines 2‑6) packaging the Go binary alongside a Chromium installation auto-downloaded by go-rod. Unit tests use github.com/stretchr/testify, with examples in publish_test.go.

How the Components Integrate

The architecture follows a layered approach:

1. Entry Point: main.go bootstraps an AppServer that wraps both the MCP server and Gin router.
2. Protocol Translation: The MCP endpoint receives streaming JSON payloads via NewStreamableHTTPHandler and forwards them to service methods.
3. Browser Orchestration: Service methods instantiate rod.New().MustConnect() to spawn Chromium pages, executing login or publishing workflows.
4. Session Management: The login.go module authenticates users via QR-code scanning before any publishing actions occur, storing session state for subsequent requests.

This stack enables xiaohongshu-mcp to expose complex web UI interactions as simple API calls, making it compatible with automation platforms like n8n or custom AI agents.

Summary

• Go 1.24 provides the runtime and concurrency model for the entire service, defined in go.mod.
• Gin-Gonic handles HTTP routing and middleware in routes.go and middleware.go.
• MCP Go SDK implements the Model Context Protocol server in app_server.go.
• go-rod with stealth plugin drives browser automation for Xiaohongshu interactions in login.go and publish.go.
• logrus and retry-go provide observability and resilience.
• Docker containerizes the application with Chromium for reproducible deployments.

Frequently Asked Questions

What programming language is xiaohongshu-mcp built with?

The project is built entirely with Go 1.24, as specified in the go.mod file. Go’s static typing and goroutine-based concurrency make it suitable for handling multiple simultaneous browser sessions and HTTP connections.

How does xiaohongshu-mcp automate browser interactions?

The project uses go-rod, a Chrome DevTools Protocol library, to control headless Chromium instances. It includes the stealth plugin to avoid detection, enabling automated login via QR-code scanning and content publishing as implemented in xiaohongshu/login.go and xiaohongshu/publish.go.

What is the role of the MCP SDK in this project?

The modelcontextprotocol/go-sdk implements the Model Context Protocol server specification, allowing AI clients to stream requests to the /mcp endpoint. This bridges the gap between language models and the Xiaohongshu platform, as configured in app_server.go using NewStreamableHTTPHandler.

Can xiaohongshu-mcp run in a containerized environment?

Yes, the repository includes a Dockerfile that packages the Go service with a Chromium binary. The container setup ensures consistent deployment across environments, with go-rod automatically managing the browser installation at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}