# xiaohongshu-mcp HTTP API Endpoints: Complete REST Reference

> Explore over 20 comprehensive xiaohongshu-mcp HTTP API endpoints. Access our complete REST reference for health monitoring, content publishing, feed operations, and social interactions.

- Repository: [zy/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Tags: api-reference
- Published: 2026-03-09

---

**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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go) and implemented in [`handlers_api.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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.

```bash

# 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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go)), HTTP handlers ([`handlers_api.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/handlers_api.go), which uses standardized `ErrorResponse` and `SuccessResponse` structures and delegates business logic to the `xiaohongshu/` package.