xiaohongshu-mcp/docs/API.md

小红书 MCP HTTP API 文档

概述

该项目提供了小红书 MCP (Model Context Protocol) 服务的 HTTP API 接口，同时支持 MCP 协议和标准的 HTTP REST API。本文档描述了 HTTP API 的使用方法。

Base URL: http://localhost:8080

注意: 以下响应示例仅展示主要字段结构，完整的字段信息请通过实际API调用查看。

通用响应格式

所有 API 响应都使用统一的 JSON 格式：

成功响应

{
  "success": true,
  "data": {},
  "message": "操作成功消息"
}

错误响应

{
  "error": "错误消息",
  "code": "ERROR_CODE",
  "details": "详细错误信息"
}

API 端点

1. 健康检查

检查服务状态。

请求

GET /health

响应

{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "xiaohongshu-mcp",
    "account": "ai-report",
    "timestamp": "now"
  },
  "message": "服务正常"
}

---

2. 登录管理

2.1 检查登录状态

检查当前用户的登录状态。

请求

GET /api/v1/login/status

响应

{
  "success": true,
  "data": {
    "is_logged_in": true,
    "username": "用户名"
  },
  "message": "检查登录状态成功"
}

2.2 获取登录二维码

获取登录二维码，用于用户扫码登录。

请求

GET /api/v1/login/qrcode

响应

{
  "success": true,
  "data": {
    "timeout": "300",
    "is_logged_in": false,
    "img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "message": "获取登录二维码成功"
}

响应字段说明:

• timeout: 二维码过期时间（秒）
• is_logged_in: 当前是否已登录
• img: Base64 编码的二维码图片

---

3. 内容发布

发布笔记内容到小红书。

请求

POST /api/v1/publish
Content-Type: application/json

请求体

{
  "title": "笔记标题",
  "content": "笔记内容",
  "images": [
    "http://example.com/image1.jpg",
    "http://example.com/image2.jpg"
  ],
  "tags": ["标签1", "标签2"]
}

请求参数说明:

• title (string, required): 笔记标题
• content (string, required): 笔记内容
• images (array, required): 图片URL数组，至少包含一张图片
• tags (array, optional): 标签数组

响应

{
  "success": true,
  "data": {
    "title": "笔记标题",
    "content": "笔记内容",
    "images": 2,
    "status": "published",
    "post_id": "64f1a2b3c4d5e6f7a8b9c0d1"
  },
  "message": "发布成功"
}

---

4. Feed 管理

4.1 获取 Feeds 列表

获取用户的 Feeds 列表。

请求

GET /api/v1/feeds/list

响应

{
  "success": true,
  "data": {
    "feeds": [
      {
        "xsecToken": "security_token_value",
        "id": "feed_id_1",
        "modelType": "note",
        "noteCard": {
          "type": "normal",
          "displayTitle": "笔记标题",
          "user": {
            "userId": "user_id_1",
            "nickname": "用户昵称",
            "avatar": "https://example.com/avatar.jpg"
          },
          "interactInfo": {
            "likedCount": "100",
            "commentCount": "50"
          },
          "cover": {
            "url": "https://example.com/cover.jpg"
          }
        },
        "index": 0
      }
    ],
    "count": 10
  },
  "message": "获取Feeds列表成功"
}

4.2 搜索 Feeds

根据关键词搜索 Feeds。

请求

GET /api/v1/feeds/search?keyword=搜索关键词

查询参数:

• keyword (string, required): 搜索关键词

响应

{
  "success": true,
  "data": {
    "feeds": [
      {
        "xsecToken": "security_token_value",
        "id": "feed_id_1",
        "modelType": "note",
        "noteCard": {
          "displayTitle": "相关笔记标题",
          "user": {
            "userId": "user_id_1",
            "nickname": "用户昵称"
          },
          "interactInfo": {
            "likedCount": "80",
            "commentCount": "35"
          }
        },
        "index": 0
      }
    ],
    "count": 5
  },
  "message": "搜索Feeds成功"
}

4.3 获取 Feed 详情

获取指定 Feed 的详细信息。

请求

POST /api/v1/feeds/detail
Content-Type: application/json

请求体

{
  "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "xsec_token": "security_token_here"
}

请求参数说明:

• feed_id (string, required): Feed ID
• xsec_token (string, required): 安全令牌

响应

{
  "success": true,
  "data": {
    "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "data": {
      "note": {
        "noteId": "64f1a2b3c4d5e6f7a8b9c0d1",
        "title": "笔记标题",
        "desc": "笔记详细内容描述",
        "user": {
          "userId": "user_id_123",
          "nickname": "作者昵称"
        },
        "interactInfo": {
          "likedCount": "100",
          "commentCount": "50"
        },
        "imageList": [
          {
            "urlDefault": "https://example.com/image1_default.jpg"
          }
        ]
      },
      "comments": {
        "list": [
          {
            "id": "comment_id_1",
            "content": "评论内容",
            "userInfo": {
              "nickname": "评论者昵称"
            }
          }
        ],
        "hasMore": true
      }
    }
  },
  "message": "获取Feed详情成功"
}

---

5. 用户信息

获取用户主页信息。

请求

POST /api/v1/user/profile
Content-Type: application/json

请求体

{
  "user_id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "xsec_token": "security_token_here"
}

请求参数说明:

• user_id (string, required): 用户ID
• xsec_token (string, required): 安全令牌

响应

{
  "success": true,
  "data": {
    "data": {
      "userBasicInfo": {
        "nickname": "用户昵称",
        "desc": "用户个人描述",
        "redId": "xiaohongshu_id"
      },
      "interactions": [
        {
          "type": "follows",
          "name": "关注",
          "count": "1000"
        },
        {
          "type": "fans",
          "name": "粉丝",
          "count": "5000"
        }
      ],
      "feeds": [
        {
          "id": "feed_id_1",
          "noteCard": {
            "displayTitle": "用户的笔记标题"
          }
        }
      ]
    }
  },
  "message": "获取用户主页成功"
}

---

6. 评论管理

6.1 发表评论

对指定 Feed 发表评论。

请求

POST /api/v1/feeds/comment
Content-Type: application/json

请求体

{
  "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "xsec_token": "security_token_here",
  "content": "评论内容"
}

请求参数说明:

• feed_id (string, required): Feed ID
• xsec_token (string, required): 安全令牌
• content (string, required): 评论内容

响应

{
  "success": true,
  "data": {
    "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "success": true,
    "message": "评论发表成功"
  },
  "message": "评论发表成功"
}

---

注意事项

1. 认证: 部分 API 需要有效的登录状态，建议先调用登录状态检查接口确认登录。

2. 安全令牌: xsec_token 是小红书的安全令牌，在调用需要该参数的接口时必须提供。

3. 图片上传: 发布接口中的 images 参数需要提供可访问的图片URL。

4. 错误处理: 所有接口在出错时都会返回统一格式的错误响应，请根据 code 字段进行相应的错误处理。

5. 日志记录: 所有API调用都会被记录到服务日志中，包括请求方法、路径和状态码。

6. 跨域支持: API 支持跨域请求 (CORS)。

MCP 协议支持

除了上述HTTP API，本服务同时支持 MCP (Model Context Protocol) 协议：

• MCP 端点: /mcp 和 /mcp/*path
• 协议类型: 支持 JSON 响应格式的 Streamable HTTP
• 用途: 可以通过MCP客户端调用相同的功能

更多MCP协议相关信息请参考 Model Context Protocol 官方文档。