SocialDataX 小红书 Xiaohongshu XHS RedNote MCP

xhs_get_topic_notes_by_topic_url

Read-only

根据话题页链接、短链接或分享文案获取标签页笔记列表，支持 sort_type 排序和 page_token 翻页。

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sort_type`	No	标签页笔记排序方式，可选：hot（最热，默认）、time_descending（最新）	hot
`topic_url`	Yes	小红书话题页链接、短链接或分享文案。支持以下形式：1) xiaohongshu.com/topic/normal/... 话题页长链；2) xhslink.com / xhslink.cn / xhsurl.com / xhsurl.cn 短链接；3) 包含上述任一链接的完整分享文案。
`page_token`	No	分页令牌。首次请求留空；继续翻页时必须将上一页返回的完整 next_page_token 原样作为 page_token 传回。page_token 是不透明分页令牌，只绑定当前标签页和排序链路，不能跨 page_id 或排序复用；不得修改、截断、缩写、脱敏、掩码、省略、规范化、重组或自行生成，不得用省略号替换中间内容。

Output Schema

TableJSON Schema

Name	Required	Description
`items`	Yes	标签页笔记列表
`points`	Yes	本次成功调用的积分消耗与调用完成时的账户积分余额。
`next_page_token`	Yes	下一页不透明分页令牌；非空表示可尝试请求下一页，为空表示当前没有可继续的下一页令牌。继续翻页时必须将返回的完整 next_page_token 原样作为 page_token 传回。next_page_token 只绑定当前标签页和排序链路，不能跨 page_id 或排序复用；items 为空时不要单独据此判断结束；不得修改、截断、缩写、脱敏、掩码、省略、规范化、重组或自行生成，不得用省略号替换中间内容。
`total_note_count`	Yes	标签页笔记总数
`total_user_count`	Yes	标签页涉及用户总数

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedAug 26, 2026

addedOutput schema / properties / items / items / properties / image_items / items / properties / height

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "图片高度，像素；没有时为 null"
+}

addedOutput schema / properties / items / items / properties / image_items / items / properties / width

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "图片宽度，像素；没有时为 null"
+}

changedOutput schema / properties / items / items / properties / image_items / items / required

Previous value: -[
-  "image_url"
-]New value: +[
+  "image_url",
+  "width",
+  "height"
+]

changedOutput schema / properties / items / items / properties / video / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "duration_ms": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "视频原始时长，单位毫秒；没有时长时为 null"
-      },
-      "video_url": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "视频链接；没有视频链接时为 null"
-      }
-    },
-    "required": [
-      "video_url",
-      "duration_ms"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "duration_ms": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "视频原始时长，单位毫秒；没有时长时为 null"
+      },
+      "height": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "视频高度，像素；没有时为 null"
+      },
+      "video_url": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "视频链接；没有视频链接时为 null"
+      },
+      "width": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "视频宽度，像素；没有时为 null"
+      }
+    },
+    "required": [
+      "video_url",
+      "duration_ms",
+      "width",
+      "height"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedAug 24, 2026

changedOutput schema / properties / items / items / properties / note_id / description

Previous value: -"note_id 是小红书笔记 ID。必须原样复制笔记搜索、笔记详情、评论、标签页笔记列表或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"New value: +"note_id 是小红书笔记 ID。已有完整 note_id 时原样使用；否则可从笔记搜索、笔记详情、评论、标签页笔记列表或用户发帖列表结果复制；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"

Changed2 schema fields changedAug 17, 2026

addedOutput schema / properties / points

Added value: +{
+  "additionalProperties": false,
+  "description": "本次成功调用的积分消耗与调用完成时的账户积分余额。",
+  "properties": {
+    "balance": {
+      "description": "本次接口完成时看到的当前积分余额。",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "cost": {
+      "description": "本次请求最终确认消耗的积分。",
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "cost",
+    "balance"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "items",
-  "next_page_token",
-  "total_note_count",
-  "total_user_count"
-]New value: +[
+  "items",
+  "next_page_token",
+  "total_note_count",
+  "total_user_count",
+  "points"
+]

Changed1 schema field changedAug 13, 2026

changedOutput schema / properties / items / items / properties / note_id / description

Previous value: -"note_id 是小红书笔记 ID。必须原样复制搜索、详情、评论、标签页笔记列表或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"New value: +"note_id 是小红书笔记 ID。必须原样复制笔记搜索、笔记详情、评论、标签页笔记列表或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"

Changed8 schema fields changedAug 12, 2026

removedOutput schema / properties / items / items / properties / collect_count
```
Removed value: -{
-  "description": "收藏数",
-  "type": "integer"
-}
```

changedOutput schema / properties / items / items / properties / image_items / description

Previous value: -"图片结构化明细；无图片时为空数组"New value: +"图片列表；无图片时为空数组"

removedOutput schema / properties / items / items / properties / image_items / items / properties / live_photo

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": false,
-      "properties": {
-        "duration_ms": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "description": "Live 图时长，单位毫秒；没有时长时为 null"
-        },
-        "video_url": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "description": "Live 图视频链接；没有视频链接时为 null"
-        }
-      },
-      "required": [
-        "video_url",
-        "duration_ms"
-      ],
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Live 图视频摘要；普通图片或没有视频摘要时为 null"
-}

changedOutput schema / properties / items / items / properties / image_items / items / required
```
Previous value: -[
-  "image_url",
-  "live_photo"
-]New value: +[
+  "image_url"
+]
```

changedOutput schema / properties / items / items / properties / note_id / description

Previous value: -"note_id 是 24 位小写十六进制稳定笔记 ID。必须原样复制搜索、详情、评论、标签页笔记或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"New value: +"note_id 是小红书笔记 ID。必须原样复制搜索、详情、评论、标签页笔记列表或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"

removedOutput schema / properties / items / items / properties / note_url

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "note_url 是可打开笔记内容所需的完整 URL。任何使用该返回链接的场景都必须原样保留完整 URL，包括 xsec_token 等 query 参数；例如最终回答、展示、引用、存储、输出或传递；不得修改、截断、脱敏、规范化、重组，也不得用 note_id 重新拼接链接。无法提供可用链接时为 null；note_url 为 null 时不要用 note_id 合成公开链接。"
-}

changedOutput schema / properties / items / items / properties / video / description

Previous value: -"视频摘要信息；仅视频笔记返回对象，图文为 null"New value: +"视频摘要信息；视频笔记有可用视频摘要时返回对象，图文或无可用视频摘要时为 null"

changedOutput schema / properties / items / items / required

Previous value: -[
-  "note_url",
-  "note_id",
-  "note_type",
-  "title",
-  "cover_image_url",
-  "image_items",
-  "video",
-  "like_count",
-  "collect_count",
-  "publish_time",
-  "author"
-]New value: +[
+  "note_id",
+  "note_type",
+  "title",
+  "cover_image_url",
+  "image_items",
+  "video",
+  "like_count",
+  "publish_time",
+  "author"
+]

Changed18 schema fields changedAug 8, 2026

removedInput schema / properties / page

Removed value: -{
-  "default": 1,
-  "description": "页码，从 1 开始",
-  "type": "integer"
-}

removedInput schema / properties / page_size

Removed value: -{
-  "default": 20,
-  "description": "每页笔记数量",
-  "type": "integer"
-}

addedInput schema / properties / page_token

Added value: +{
+  "default": "",
+  "description": "分页令牌。首次请求留空；继续翻页时必须将上一页返回的完整 next_page_token 原样作为 page_token 传回。page_token 是不透明分页令牌，只绑定当前标签页和排序链路，不能跨 page_id 或排序复用；不得修改、截断、缩写、脱敏、掩码、省略、规范化、重组或自行生成，不得用省略号替换中间内容。",
+  "type": "string"
+}

removedInput schema / properties / sort

Removed value: -{
-  "default": "hot",
-  "description": "话题/标签页笔记排序方式，可选：hot（最热，默认）、time（最新）",
-  "enum": [
-    "hot",
-    "time"
-  ],
-  "type": "string"
-}

addedInput schema / properties / sort_type

Added value: +{
+  "default": "hot",
+  "description": "标签页笔记排序方式，可选：hot（最热，默认）、time_descending（最新）",
+  "enum": [
+    "hot",
+    "time_descending"
+  ],
+  "type": "string"
+}

removedOutput schema / properties / has_more

Removed value: -{
-  "description": "是否还有下一页",
-  "type": "boolean"
-}

changedOutput schema / properties / items / description

Previous value: -"话题页笔记列表"New value: +"标签页笔记列表"

addedOutput schema / properties / items / items / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / items / items / properties / image_items

Added value: +{
+  "description": "图片结构化明细；无图片时为空数组",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "image_url": {
+        "description": "图片链接",
+        "type": "string"
+      },
+      "live_photo": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "duration_ms": {
+                "anyOf": [
+                  {
+                    "type": "integer"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Live 图时长，单位毫秒；没有时长时为 null"
+              },
+              "video_url": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Live 图视频链接；没有视频链接时为 null"
+              }
+            },
+            "required": [
+              "video_url",
+              "duration_ms"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Live 图视频摘要；普通图片或没有视频摘要时为 null"
+      }
+    },
+    "required": [
+      "image_url",
+      "live_photo"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / items / items / properties / note_id / description

Previous value: -"note_id 是 24 位小写十六进制稳定笔记 ID。必须原样复制搜索、详情、评论或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"New value: +"note_id 是 24 位小写十六进制稳定笔记 ID。必须原样复制搜索、详情、评论、标签页笔记或用户发帖列表返回的完整 note_id；不得截断、缩写、脱敏、补全、格式化、重组，也不得只传前缀。"

changedOutput schema / properties / items / items / properties / note_url / description

Previous value: -"可打开笔记内容的完整 URL；没有可用链接时为 null"New value: +"note_url 是可打开笔记内容所需的完整 URL。任何使用该返回链接的场景都必须原样保留完整 URL，包括 xsec_token 等 query 参数；例如最终回答、展示、引用、存储、输出或传递；不得修改、截断、脱敏、规范化、重组，也不得用 note_id 重新拼接链接。无法提供可用链接时为 null；note_url 为 null 时不要用 note_id 合成公开链接。"

removedOutput schema / properties / items / items / properties / summary

Removed value: -{
-  "description": "笔记摘要；不是全文",
-  "type": "string"
-}

changedOutput schema / properties / items / items / properties / video / anyOf

Previous value: -[
-  {
-    "properties": {
-      "duration_ms": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "视频原始时长，单位毫秒；没有时长时为 null"
-      },
-      "video_url": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "视频链接；没有视频链接时为 null"
-      }
-    },
-    "required": [
-      "video_url",
-      "duration_ms"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "duration_ms": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "视频原始时长，单位毫秒；没有时长时为 null"
+      },
+      "video_url": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "视频链接；没有视频链接时为 null"
+      }
+    },
+    "required": [
+      "video_url",
+      "duration_ms"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / items / items / required

Previous value: -[
-  "note_url",
-  "note_id",
-  "note_type",
-  "title",
-  "summary",
-  "cover_image_url",
-  "like_count",
-  "collect_count",
-  "publish_time",
-  "video",
-  "author"
-]New value: +[
+  "note_url",
+  "note_id",
+  "note_type",
+  "title",
+  "cover_image_url",
+  "image_items",
+  "video",
+  "like_count",
+  "collect_count",
+  "publish_time",
+  "author"
+]

addedOutput schema / properties / next_page_token

Added value: +{
+  "description": "下一页不透明分页令牌；非空表示可尝试请求下一页，为空表示当前没有可继续的下一页令牌。继续翻页时必须将返回的完整 next_page_token 原样作为 page_token 传回。next_page_token 只绑定当前标签页和排序链路，不能跨 page_id 或排序复用；items 为空时不要单独据此判断结束；不得修改、截断、缩写、脱敏、掩码、省略、规范化、重组或自行生成，不得用省略号替换中间内容。",
+  "type": "string"
+}

changedOutput schema / properties / total_note_count / description

Previous value: -"话题页笔记总数"New value: +"标签页笔记总数"

changedOutput schema / properties / total_user_count / description

Previous value: -"话题页涉及用户总数"New value: +"标签页涉及用户总数"

changedOutput schema / required

Previous value: -[
-  "items",
-  "has_more",
-  "total_note_count",
-  "total_user_count"
-]New value: +[
+  "items",
+  "next_page_token",
+  "total_note_count",
+  "total_user_count"
+]

AddedAug 7, 2026

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds only that sorting and pagination are supported, which is already visible in the schema; it contributes little extra behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence states the purpose and key capabilities with no filler. Every element in the description earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full input schema, output schema, and read-only annotations, the description is sufficient for an agent to select and invoke the tool correctly. It could add an explicit pointer to xhs_get_topic_notes_by_page_id for page-ID scenarios, but that is a routing nicety, not an invocation gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents topic_url formats, sort_type enum, and page_token behavior. The description only restates that sorting and pagination are supported, adding no new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it fetches the topic notes list from a topic URL, short link, or share text. This also differentiates it from the sibling xhs_get_topic_notes_by_page_id, which uses a page ID instead of a URL.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended trigger explicit: use this tool when the caller has a topic page link, short link, or share text. It does not mention the page_id alternative or state exclusions, so it misses the full 'when not to use' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All SocialDataX 小红书 Xiaohongshu XHS RedNote MCP tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?