# 小红书 MCP | Xiaohongshu MCP | XHS MCP | RedNote MCP

LobeHub 用户请使用 [LobeHub setup / 接入说明](LOBEHUB.md)，包含专属官网入口、认证和来源配置。

This public repository provides public connection docs and MCP metadata for a hosted 小红书 MCP / Xiaohongshu MCP / XHS MCP / RedNote MCP service.

If you are looking for a 小红书 MCP, Xiaohongshu MCP, XHS MCP, or RedNote MCP for social media research workflows, this repository includes:

- public MCP metadata and client configuration examples
- the hosted `streamable-http` endpoint for clients that support remote MCP
- command/stdio configurations for the npm bridge and direct `mcp-remote` use

The business implementation is privately hosted. This repository exposes only the public connection surface for social media content intelligence workflows.

## Search Aliases

Common search phrases for this MCP service:

- `小红书 MCP`
- `小红书 数据 MCP`
- `小红书 搜索 MCP`
- `小红书 XHS MCP`
- `Xiaohongshu MCP`
- `Xiaohongshu data MCP`
- `XHS MCP`
- `XHS data MCP`
- `RedNote MCP`
- `RedNote data MCP`
- `Xiaohongshu note search MCP`

## Service

- Hosted MCP endpoint: `https://mcp.socialdatax.com/xhs/mcp`
- Hosted transport: `streamable-http`
- Authentication: `Authorization: Bearer <SOCIALDATAX_API_KEY>`
- Product: `SocialDataX` / `社媒数据助手`
- Website and API Key access: <https://socialdatax.com/ai?from=github>
- Registry name: `com.52choujiang/xhs-insights`
- Future registry name: `com.socialdatax/xhs-insights`
- Current public capability version: `0.1.15` (35 tools)
- Hosted production: `0.1.15` with 35 tools; deployment and authenticated tool discovery verified on `2026-10-14`. Video notes remain available through `xhs_search_notes(note_type="video")`.
- Official MCP Registry: `0.1.15` (`active`, `isLatest=true`), published and verified on `2026-10-14`.
- Public GitHub server card: `0.1.15` with 35 tools, synced and verified on `2026-10-14`.
- The public tool catalog is maintained in [`server-card.json`](server-card.json); npm bridge versions are independent of the hosted tool catalog.
- npm stdio bridge: `xiaohongshu-xhs-rednote-mcp@0.1.18`; bridge package versions are independent of hosted capability versions.

The current capability includes encrypted user ID resolution, PGY creator profiles, note performance, fans profiles and fans summaries, product review reply-reply lookup, product detail lookup by URL, and the product detail field rename (`images` to `main_images`; `detail_images` remains unchanged).

## Platform MCP

Use the hosted `streamable-http` endpoint directly from clients that support authenticated remote MCP. Command/stdio clients can use the npm bridge in `mcp.json` or configure `mcp-remote` directly.

## npm stdio bridge

Requires Node.js 20.18.1 or later.

Command/stdio-only MCP clients can install and start the bridge directly from npm:

```json
{
  "mcpServers": {
    "socialdatax-xhs": {
      "command": "npx",
      "args": ["-y", "xiaohongshu-xhs-rednote-mcp"],
      "env": {
        "SOCIALDATAX_API_KEY": "<SOCIALDATAX_API_KEY>"
      }
    }
  }
}
```

The package only forwards local stdio MCP messages to the hosted SocialDataX XHS endpoint. It does not contain the private service implementation or store the API Key.

The public tool catalog can be discovered without an API Key. Set `SOCIALDATAX_API_KEY` for business tool calls; without it, the bridge can start for discovery, while the hosted service requires authentication for business data.

## Workflow Scope

This MCP service is designed for social media content intelligence workflows. It does not provide account login, posting, editing, liking, commenting, or other account actions.

Supported workflows include:

- Query the current API Key account's SocialDataX points balance / 积分余额、剩余积分或点数.
- Search related Xiaohongshu notes by keyword, with optional sort, note type, and publish-time filters.
- Search Xiaohongshu products by keyword with page_token continuation.
- Fetch product details by a complete sku_id supplied by the user or copied from product search results.
- Fetch one PGY / 蒲公英 enhanced note detail from either a complete note_id or a note link, short link, or share text; successful calls cost 20 points and failures are not charged.
- PGY applies only to notes from enrolled creators. Use it for requested commercial data; keep ordinary note requests on ordinary detail tools. An explicit no-commercial-data result is treated as not enrolled (`pgy_commercial_data_unavailable`); stop without retrying the other ID/URL route. Timeouts, authentication failures and insufficient balance keep their own errors.
- Fetch product reviews by a complete sku_id supplied by the user or copied from product search results.
- Fetch nested replies under a product review reply by a `review_id` supplied by the user or copied from `xhs_get_product_review_replies`; accepts opaque `page_token` continuation and does not accept `root_review_id`.
- Read the Xiaohongshu search hot list with title and heat value.
- Read Xiaohongshu search suggestions for a keyword or partial phrase.
- Resolve a shared note link, short link, or share text into structured note details.
- Read note details when the caller already has a note ID.
- Fetch paginated first-level comments for comment analysis.
- Fetch paginated replies under a first-level comment.
- Read creator profile data from a profile link, short link, share text, or user ID.
- Fetch paginated creator note lists from a user ID, profile link, short link, or share text for content style and account research.
- Fetch paginated tag page note lists from a topic URL, short link, share text, or page ID.
- Submit a video note speech-to-text transcript task; the submit call may wait up to 240 seconds, and unfinished jobs should continue polling the same `job_id` until terminal.

## Tools

| Tool | Public purpose |
| --- | --- |
| `socialdatax_get_points_balance` | Query the current API Key account's SocialDataX points balance / 积分余额、剩余积分或点数. |
| `xhs_search_users` | Search Xiaohongshu / 小红书 users, accounts, or creators by keyword with `page_token` pagination. When a user ID or profile URL is already available, use the corresponding user-profile tool. |
| `xhs_search_notes` | Search Xiaohongshu / 小红书 notes, including video notes with `note_type="video"` and image notes with `note_type="image"`; supports sorting, publish-time filters, and `page_token` continuation. Use the corresponding detail tool when the caller already has a note link or `note_id` and needs one note's details; use the corresponding URL/ID tool for comments, replies, or speech-to-text. To continue search pagination, pass the full returned `next_page_token` back unchanged as `page_token`; omit `page_token` on the first request. In every use of a returned `note_url`, such as final answers, display, references, storage, output, or forwarding, preserve the full URL exactly, including `xsec_token`; do not rebuild links from `note_id`. |
| `xhs_search_images` | Search Xiaohongshu images by keyword; each result is one image with its associated note, and one note may contribute multiple images. Pagination may return no further results. For image notes, use `xhs_search_notes` with `note_type="image"`. |
| `xhs_search_products` | Search Xiaohongshu products by product name, brand, category, or product-related query, with `page_token` continuation. Use this tool for search terms; if a complete `sku_id` is already available, including one supplied by the user, use `xhs_get_product_detail_by_sku_id` or `xhs_get_product_reviews` instead. Do not use product links, `sku_id`, `spu_id`, or `page_token` as the keyword. To continue product search pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_product_detail_by_sku_id` | Fetch Xiaohongshu product details by a complete `sku_id` supplied by the user or copied from `xhs_search_products` results. For product links or share text, use `xhs_get_product_detail_by_url`. This ID tool does not accept `spu_id`, product links, or search keywords. |
| `xhs_get_product_detail_by_url` | Fetch Xiaohongshu product details from a product URL, short link, or share text containing a product link, without searching first. Returns the same fields as `xhs_get_product_detail_by_sku_id`; the returned `sku_id` can be used to read product reviews. Note links, profile links, and standalone share codes are not supported. |
| `xhs_pgy_get_note_detail_by_note_id` | Fetch one Xiaohongshu PGY / 蒲公英 enhanced note detail when the caller already has a complete `note_id`, including content, images or a video summary, author, exposure, reads, likes, saves, comments, shares, and creator image/video collaboration quotes in Chinese yuan. The quotes are not the note's transaction price. Only notes from PGY-enrolled creators are eligible. This is PGY commercial data, not ordinary public note detail; successful calls cost 20 points and failures are not charged. |
| `xhs_pgy_get_note_detail_by_note_url` | Fetch one Xiaohongshu PGY / 蒲公英 enhanced note detail from a complete note link, short link, or share text, with the same PGY commercial output and creator image/video collaboration quotes in Chinese yuan. The quotes are not the note's transaction price. Only notes from enrolled creators are eligible. Successful calls cost 20 points and failures are not charged. |
| `xhs_pgy_get_creator_profile` | Fetch a Xiaohongshu PGY / 蒲公英 creator profile by a complete `user_id`, including creator and commercial-note scale, cooperation industries, note medians, content tags, and creator image/video collaboration quotes in Chinese yuan. Use ordinary user-profile tools for non-PGY account data. Successful calls cost 20 points and failures are not charged. |
| `xhs_pgy_get_creator_notes_performance` | Fetch Xiaohongshu PGY / 蒲公英 creator note performance by a complete `user_id`, including note counts, exposure/read/interaction medians, interaction rate, video completion rate, image three-second read rate, content tags, and note items. Optional `note_scope` selects `daily` (default) or `cooperation`; the response echoes the scope. Note items cover at most the latest 15 notes. Only `notes[]` comparison rates are signed differences relative to platform medians and may be negative or exceed 1; same-named summary comparison fields are opaque 0-to-1 platform values and must not be mixed. Successful calls cost 20 points and failures are not charged. |
| `xhs_pgy_get_creator_fans_profile` | Fetch PGY fan distributions and their data date by a complete `user_id`. Ratios use 0–1 decimals; distributions may be incomplete. Successful calls cost 20 points; failures are not charged. |
| `xhs_pgy_get_creator_fans_summary` | Fetch PGY follower counts, growth, activity, reading and engagement metrics by a complete `user_id`. Window end dates and growth periods are unspecified. Successful calls cost 20 points; failures are not charged. |
| `xhs_pgy_get_creator_metrics_trend` | Fetch date-indexed medians and estimated costs. Requires user_id; note_scope defaults to daily, while cooperation includes outbound store metrics. Fixed image + video, last 30 days, all traffic for medians; costs use field-specific scopes. Gaps are preserved; values cannot be summed across dates. Successful calls cost 20 points; failures are not charged. |
| `xhs_pgy_get_creator_commercial_overview` | Fetch PGY commercial metrics and estimated costs. Requires user_id; note_scope defaults to daily, while cooperation includes outbound store visits. Successful calls cost 20 points; failures are not charged. |
| `xhs_get_product_reviews` | Fetch Xiaohongshu product reviews by a complete `sku_id` supplied by the user or copied from `xhs_search_products` results; accepts `sort_type`: `general` (comprehensive sort, the default) or `time_descending`, `has_image`, and `page_token` continuation. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. This tool does not accept `spu_id`, product links, or search keywords. |
| `xhs_get_product_review_replies` | Fetch replies under a first-level Xiaohongshu product review. Use a user-provided `review_id`, or obtain one from `xhs_get_product_reviews`; accepts opaque `page_token` continuation. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. This tool does not accept `root_review_id`. |
| `xhs_get_product_review_reply_replies` | Fetch nested replies under a Xiaohongshu product review reply. Use a user-provided reply `review_id`, or obtain one from `xhs_get_product_review_replies`; accepts opaque `page_token` continuation. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. This tool does not accept `root_review_id`. |
| `xhs_get_search_hot_list` | Get the Xiaohongshu / 小红书 search hot list with each item's title and heat value. |
| `xhs_search_suggestions` | Get Xiaohongshu / 小红书 search suggestions for a keyword or partial phrase, including suggestion text, search target, and an optional description. |
| `xhs_get_note_detail_by_note_url` | Resolve a shared XHS link, short link, or share text into structured note details. In every use of a returned `note_url`, such as final answers, display, references, storage, output, or forwarding, preserve the full URL exactly, including `xsec_token`; do not rebuild links from `note_id`. If `note_url` is null, do not synthesize or rebuild a public link from `note_id`. |
| `xhs_get_note_detail_by_note_id` | Fetch structured note details when the caller already has a note ID. If `note_url` is returned, preserve the full URL exactly in every use, such as final answers, display, references, storage, output, or forwarding, including `xsec_token`; do not rebuild links from `note_id`. If `note_url` is null, do not synthesize or rebuild a public link from `note_id`. |
| `xhs_get_note_comments_by_note_id` | Fetch paginated first-level comments when the caller already has a note ID; accepts optional comment `sort_type`: `default`, `time_descending`, or `like_count_descending`. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_note_comments_by_note_url` | Fetch paginated first-level comments directly from a shared note URL, short link, or share text; accepts optional comment `sort_type`: `default`, `time_descending`, or `like_count_descending`. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_note_sub_comments_by_comment_id` | Fetch paginated replies under a first-level comment by note ID and comment ID. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_user_id_by_encrypted_user_id` | Resolve a complete encrypted XHS user ID to a stable `user_id`, which can then be used with creator profile and posted-note tools. |
| `xhs_get_user_info_by_user_id` | Fetch creator profile data when the caller already has a user ID. |
| `xhs_get_user_info_by_profile_url` | Resolve a profile link, short link, or share text into creator profile data. |
| `xhs_get_user_posted_notes_by_user_id` | Fetch a paginated list of notes published by a creator when the caller already has a user ID. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_user_posted_notes_by_profile_url` | Fetch a paginated list of notes published by a creator from a profile link, short link, or share text. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_topic_notes_by_topic_url` | Fetch a paginated tag page note list from a topic URL, short link, or share text; accepts `sort_type`: `hot` or `time_descending`. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_get_topic_notes_by_page_id` | Fetch a paginated tag page note list when the caller already has the tag page `page_id`; accepts `sort_type`: `hot` or `time_descending`. To continue pagination, pass the full returned `next_page_token` back unchanged as `page_token`; do not truncate, summarize, mask, or replace the middle with ellipses. |
| `xhs_submit_video_speech_text_by_note_url` | Submit a video note speech-to-text transcript task from a note link, short link, or share text. The submit call may wait up to 240 seconds; if unfinished, continue polling the same `job_id` until terminal. |
| `xhs_submit_video_speech_text_by_note_id` | Submit a video note speech-to-text transcript task from a `note_id`. The submit call may wait up to 240 seconds; if unfinished, continue polling the same `job_id` until terminal. |
| `xhs_get_video_speech_text_job` | Check a video note speech-to-text transcript job using a valid `job_id` supplied by the user, or a `job_id` returned by a submit tool; this tool does not accept `note_id` or note links and does not create a new task. Each call waits up to 240 seconds. If unfinished, continue querying the same `job_id` until terminal. This v1 surface returns transcript plus content context, not summary. |

## Quick Start

For clients that support authenticated `streamable-http`, use the hosted endpoint directly:

```json
{
  "mcpServers": {
    "socialdatax-xhs": {
      "type": "streamable_http",
      "url": "https://mcp.socialdatax.com/xhs/mcp",
      "headers": {
        "Authorization": "Bearer <SOCIALDATAX_API_KEY>"
      }
    }
  }
}
```

A ready-to-copy example is available in [`examples/streamable_http_config.json`](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/examples/streamable_http_config.json).

### Direct `mcp-remote` configuration

For command/stdio-only MCP clients, use `mcp-remote`:

```json
{
  "mcpServers": {
    "socialdatax-xhs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.socialdatax.com/xhs/mcp",
        "--header",
        "Authorization: Bearer ${SOCIALDATAX_API_KEY}"
      ],
      "env": {
        "SOCIALDATAX_API_KEY": "<SOCIALDATAX_API_KEY>"
      }
    }
  }
}
```

Claude Code can use remote HTTP directly:

```bash
claude mcp add --transport http socialdatax-xhs https://mcp.socialdatax.com/xhs/mcp --header 'Authorization: Bearer ${SOCIALDATAX_API_KEY}'
```

Persist `SOCIALDATAX_API_KEY` in the runtime environment or client Secret before restarting Claude Code.

Claude Desktop should use its remote MCP / Connectors UI when available. If your version only supports command/stdio servers, use the npm bridge or the `mcp-remote` configuration below.

## Client Examples

Configuration examples are available in [examples](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/tree/main/examples):

- [npm bridge command/stdio config](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/mcp.json)
- [Claude Desktop fallback config](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/examples/claude_desktop_config.json)
- [Direct `mcp-remote` example](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp#direct-mcp-remote-configuration)
- [Cursor remote HTTP config](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/examples/cursor_mcp.json)
- [Codex remote HTTP config](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/examples/codex_config.toml)
- [Direct streamable HTTP config](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/examples/streamable_http_config.json)

## API Key

Request or manage API access from the product website:

<https://socialdatax.com/ai?from=github>

Use the key as a Bearer token in the `Authorization` request header. Do not commit real API Key values to code, docs, issues, or screenshots.

## Directory Metadata

Public metadata files in this repository:

- [server-card.json](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/server-card.json): directory-oriented metadata for the hosted service. Official MCP Registry publishing uses the private source repo's `registry/xhs/server.json` for the current `com.52choujiang/xhs-insights` entry.
- [mcp.json](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/mcp.json): command/stdio config using the npm bridge; tool discovery works without an API Key.
- [glama.json](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/glama.json): Glama repository ownership metadata.
- [SUBMISSION_CHECKLIST.md](https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp/blob/main/SUBMISSION_CHECKLIST.md): checklist for MCP directory submissions.

## License

The files in this public repository are released under the MIT License. The license covers the public documentation and configuration examples in this repository only. It does not cover the managed service implementation, hosted infrastructure, or any private backend code outside this repository.

## Gemini CLI extension

Install this service from its public GitHub repository:

```sh
gemini extensions install https://github.com/DevinChen2014/xiaohongshu-xhs-rednote-mcp
```

When prompted, enter your own `SOCIALDATAX_API_KEY`. Get a key from [SocialDataX](https://socialdatax.com/ai?from=github); business tool calls consume SocialDataX credits. The extension connects directly to the existing hosted MCP endpoint and does not include the private service implementation.

Verify the connection with `gemini mcp list`. To change the saved key, run:

```sh
gemini extensions config socialdatax-xhs
```