astron-xiaohongshu-mcp 0.1.0

Astron-Xiaohongshu-MCP: 基于小红书公开网页与 __INITIAL_STATE__ 解析的自包含 MCP Server，支持 MCP 协议和 uvx 一键启动。

小红书公开内容 MCP Server

概述

Astron-xiaohongshu-mcp 是一个基于 MCP 协议的小红书工具服务，直接请求公开网页并解析 window.__INITIAL_STATE__，无需浏览器依赖或额外后端。

当前工程形态：

• 使用 MCP Python SDK
• 使用单文件 server.py 承载工具定义、请求封装和解析逻辑
• 通过独立 pyproject 打包
• 支持 uvx 一键启动
• 通过环境变量配置超时和 User-Agent

当前提供 6 个原子工具：

• get_hot_list
• get_feed_list
• search_content
• get_content_detail
• get_author_profile
• get_author_content_list

工具列表

1. 获取热榜 get_hot_list

• 描述：基于首页首屏公开内容做热度排序后返回。
• 参数：
  • limit：返回条数，默认 20
  • refresh：是否刷新，默认 False

2. 获取内容流 get_feed_list

• 描述：读取首页首屏公开内容流。
• 参数：
  • channel：兼容参数，当前未启用
  • cursor：分页游标，当前仅支持首屏（cursor 非空时可能返回空结果）
  • limit：返回条数，默认 20
  • refresh：是否刷新，默认 False

3. 搜索内容 search_content

• 描述：搜索公开内容（MVP，本地关键词过滤）。
• 参数：
  • query：搜索词，必填
  • cursor：兼容参数，当前未启用
  • limit：返回条数，默认 20

4. 获取内容详情 get_content_detail

• 描述：读取单条内容详情页并解析公开字段。
• 参数：
  • content_id：内容 ID
  • url：内容完整 URL

5. 获取作者主页 get_author_profile

• 描述：读取作者公开主页信息。
• 参数：
  • author_id：作者 ID
  • url：作者主页 URL

6. 获取作者公开内容列表 get_author_content_list

• 描述：读取作者主页公开内容列表。
• 参数：
  • author_id：作者 ID
  • url：作者主页 URL
  • cursor：分页游标，当前仅支持首屏
  • limit：返回条数，默认 20

搜索能力说明

由于小红书公开搜索页在游客态场景下可能存在访问限制或结果不稳定，search_content 当前采用 MVP 策略：

1. 先抓取首页首屏公开内容；
2. 在本地对标题、摘要、正文、作者名、标签进行关键词过滤；
3. 返回过滤后的结构化列表结果。

这意味着：

• 结果覆盖范围主要受“首屏样本”限制；
• 不保证等价于平台全站搜索；
• 适合“轻量检索 + 工具链联动”的基础场景。

环境变量

这个包默认不需要认证信息。

可选环境变量：

export XIAOHONGSHU_MCP_TIMEOUT_SECONDS="30"
export XIAOHONGSHU_MCP_USER_AGENT="Mozilla/5.0 ..."

说明：

• XIAOHONGSHU_MCP_TIMEOUT_SECONDS 控制页面请求超时。
• XIAOHONGSHU_MCP_USER_AGENT 用于覆盖默认请求头。

安装与启动

推荐方式：使用 uvx 一键启动

uvx --from astron-xiaohongshu-mcp astron-xiaohongshu-mcp

如果你还没有安装 uv / uvx，可先执行：

curl -fsSL https://install.astral.sh/uv | bash

使用 pip 安装

pip install astron-xiaohongshu-mcp
xiaohongshu-mcp

本地源码运行

cd MCP/xiaohongshu-mcp
PYTHONPATH=src python3 -m xiaohongshu_mcp.server

客户端配置

使用 uvx

{
  "mcpServers": {
    "xiaohongshu-mcp": {
      "command": "uvx",
      "args": ["--from", "astron-xiaohongshu-mcp", "astron-xiaohongshu-mcp"],
      "env": {
        "XIAOHONGSHU_MCP_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

使用本地源码

{
  "mcpServers": {
    "xiaohongshu-mcp": {
      "command": "python3",
      "args": ["-m", "xiaohongshu_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/MCP/xiaohongshu-mcp/src",
        "XIAOHONGSHU_MCP_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

平台差异说明

1. 当前实现只使用 requests + HTML 解析，不依赖浏览器自动化。
2. 解析核心依赖页面脚本中的 window.__INITIAL_STATE__；如页面结构变更，需要同步更新解析逻辑。
3. 仅面向游客态公开内容能力，不包含登录态、私有内容或用户专属数据。

发布说明

cd MCP/xiaohongshu-mcp
rm -rf build dist src/*.egg-info
python3 -m build --no-isolation
python3 -m twine check dist/*
python3 -m twine upload dist/*

License

Apache License 2.0. See LICENSE.