xiaohongshu-mcp HTTP API Endpoints: Complete REST Reference

The xiaohongshu-mcp server exposes 20+ HTTP API endpoints via the Gin framework, covering health monitoring, MCP protocol handling, QR code authentication, content publishing, feed operations, and social interactions.

The xiaohongshu-mcp repository implements a Model Context Protocol (MCP) server for Xiaohongshu (Little Red Book), exposing a comprehensive RESTful API layer. All HTTP API endpoints are defined in routes.go and implemented in handlers_api.go, utilizing the Gin web framework and the official MCP go-sdk for protocol handling.

Core HTTP API Endpoints in xiaohongshu-mcp

The server organizes endpoints into functional groups: system health, MCP protocol, authentication, content management, and social interactions.

Health and MCP Protocol Endpoints

These endpoints handle service monitoring and MCP protocol communication.

• GET /health — Returns service health status for load balancers and monitoring systems. Implemented in setupRoutes within routes.go.
• ANY /mcp and /mcp/*path — The MCP protocol entry point using the official go-sdk's StreamableHTTPHandler. Supports JSON responses and handles all Model Context Protocol interactions.

Authentication and Login Endpoints

Manage QR code-based authentication and session state.

• GET /api/v1/login/status — Query current login state and session validity.
• GET /api/v1/login/qrcode — Retrieve login QR code as Base64-encoded image with expiration timeout.
• DELETE /api/v1/login/cookies — Clear local cookies to force re-authentication.

All authentication handlers reside in handlers_api.go and interact with the xiaohongshu/ package for credential management.

Content Publishing Endpoints

Create and publish content to Xiaohongshu.

• POST /api/v1/publish — Publish text or image-text content. Accepts JSON payload with title, desc, and image_urls array.
• POST /api/v1/publish_video — Publish video content. Requires title, video_url, and cover_url parameters.

These endpoints delegate to xiaohongshuService methods like PublishContent for actual platform interaction.

Feed and Search Endpoints

Retrieve and search content feeds.

• GET /api/v1/feeds/list — Fetch homepage feeds list.
• GET /api/v1/feeds/search — Search feeds by keyword via query parameters.
• POST /api/v1/feeds/search — Advanced search with JSON body filters (e.g., {"type": "photo"}).
• POST /api/v1/feeds/detail — Retrieve specific feed details with optional comment loading configuration.

User and Interaction Endpoints

Manage user profiles and social interactions.

• POST /api/v1/user/profile — Fetch user homepage information by user_id.
• GET /api/v1/user/me — Retrieve current logged-in user's profile.
• POST /api/v1/feeds/comment — Post comments to feeds.
• POST /api/v1/feeds/comment/reply — Reply to specific comments on feeds.

Implementation Architecture

The xiaohongshu-mcp HTTP API endpoints follow a layered architecture ensuring maintainability and separation of concerns.

Route Configuration — The setupRoutes function in routes.go registers all endpoints with the Gin engine. It applies global middleware for CORS, logging, and error recovery before binding handlers.

Handler Layer — handlers_api.go contains the HTTP handler implementations. It uses standardized response structures (ErrorResponse and SuccessResponse) and logrus for structured logging. Each handler validates input, calls the service layer, and returns JSON responses.

Service Layer — The xiaohongshu/ directory contains the business logic, including methods like PublishContent, SearchFeeds, and UserProfile. This layer handles the actual interaction with Xiaohongshu's web platform or internal SDKs.

MCP Integration — The /mcp endpoints bypass the standard handler structure, directly delegating to the official MCP go-sdk's StreamableHTTPHandler for protocol-compliant communication.

Practical API Usage Examples

Below are runnable curl commands demonstrating key xiaohongshu-mcp HTTP API endpoints. Replace localhost:8000 with your actual deployment address.

# Health check

curl -X GET http://localhost:8000/health

# Get login QR code (Base64 image)

curl -X GET http://localhost:8000/api/v1/login/qrcode

# Delete cookies (force logout)

curl -X DELETE http://localhost:8000/api/v1/login/cookies

# Publish image-text content

curl -X POST http://localhost:8000/api/v1/publish \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello World","desc":"Demo post","image_urls":["https://example.com/img1.jpg"]}'

# Publish video content

curl -X POST http://localhost:8000/api/v1/publish_video \
  -H "Content-Type: application/json" \
  -d '{"title":"My Video","video_url":"https://example.com/video.mp4","cover_url":"https://example.com/cover.jpg"}'

# Get homepage feeds

curl -X GET http://localhost:8000/api/v1/feeds/list

# Search feeds (GET method)

curl -G http://localhost:8000/api/v1/feeds/search --data-urlencode "keyword=travel"

# Search feeds (POST method with filters)

curl -X POST http://localhost:8000/api/v1/feeds/search \
  -H "Content-Type: application/json" \
  -d '{"keyword":"food","filters":{"type":"photo"}}'

# Get feed details

curl -X POST http://localhost:8000/api/v1/feeds/detail \
  -H "Content-Type: application/json" \
  -d '{"feed_id":"123456","xsec_token":"xxxx","load_all_comments":true}'

# Get user profile

curl -X POST http://localhost:8000/api/v1/user/profile \
  -H "Content-Type: application/json" \
  -d '{"user_id":"98765","xsec_token":"xxxx"}'

# Post comment

curl -X POST http://localhost:8000/api/v1/feeds/comment \
  -H "Content-Type: application/json" \
  -d '{"feed_id":"123456","xsec_token":"xxxx","content":"Great post!"}'

# Reply to comment

curl -X POST http://localhost:8000/api/v1/feeds/comment/reply \
  -H "Content-Type: application/json" \
  -d '{"feed_id":"123456","xsec_token":"xxxx","comment_id":"cmt789","user_id":"98765","content":"Thanks!"}'

# Get current user info

curl -X GET http://localhost:8000/api/v1/user/me

Note: Endpoints requiring xsec_token (such as feed details, user profiles, and comments) obtain this token after successful login from the frontend or previous API responses.

Summary

The xiaohongshu-mcp HTTP API endpoints provide comprehensive programmatic access to Xiaohongshu functionality through a well-structured REST interface:

• 20+ endpoints covering health monitoring, MCP protocol, QR login, content publishing, feed management, and social interactions
• Gin framework implementation with clean separation between route configuration (routes.go), HTTP handlers (handlers_api.go), and business logic (xiaohongshu/ package)
• MCP protocol support via the official go-sdk's StreamableHTTPHandler for model context protocol integration
• Standardized responses using ErrorResponse and SuccessResponse structures with structured logging via logrus

Frequently Asked Questions

What authentication method does xiaohongshu-mcp use?

The server implements QR code-based authentication through the /api/v1/login/qrcode endpoint, which returns a Base64-encoded QR image. After scanning, the /api/v1/login/status endpoint verifies session establishment. Cookies are persisted locally and can be cleared via DELETE /api/v1/login/cookies to force re-authentication.

How does the MCP protocol endpoint differ from other API endpoints?

The /mcp and /mcp/*path endpoints bypass the standard Gin handler structure used by other xiaohongshu-mcp HTTP API endpoints. Instead, they delegate directly to the official MCP go-sdk's StreamableHTTPHandler, enabling protocol-compliant communication with external model platforms and supporting streaming JSON responses for Model Context Protocol interactions.

What is the difference between the two search endpoints?

The server provides dual search interfaces for flexibility: GET /api/v1/feeds/search accepts simple keyword queries via URL parameters (ideal for basic lookups), while POST /api/v1/feeds/search supports complex filtering through JSON request bodies (such as {"filters": {"type": "photo"}}). Both interfaces delegate to the underlying SearchFeeds method in the xiaohongshu/ service layer.

Where are the API routes and handlers defined in the source code?

Route definitions reside in routes.go within the setupRoutes function, which registers all xiaohongshu-mcp HTTP API endpoints with the Gin engine and applies global middleware. The corresponding handler implementations are located in handlers_api.go, which uses standardized ErrorResponse and SuccessResponse structures and delegates business logic to the xiaohongshu/ package.

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