> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 怎样在 Claude Code、Cursor、Codex 里用 BeatAPI 查小红书、抖音和公众号？

> 分客户端配置远程 MCP，先检查工具，再用可核对的查询结果整理社媒研究材料。

在 Claude Code、Cursor 或 Codex 里添加名为 `beatapi` 的远程 MCP 服务，`BEATAPI_API_KEY` 从环境变量读取。公开查询只需要 BeatAPI Key，不需要小红书 Cookie。配置完成后，助手会有三个工具：`capabilities_search` 查找能力，`capabilities_inspect` 查看能力的输入、价格和就绪状态，`capabilities_run` 执行能力。第一次可以让助手查一页小红书「咖啡机除垢」，列出值得点开原文的笔记。需要演示视频时再查抖音，已有公众号文章链接时直接读那篇文章的正文。

## 按客户端配置

把 `BEATAPI_API_KEY` 放进客户端进程能继承的环境变量或客户端的凭据设置，下面的配置只引用变量名。Cursor 从桌面启动时可能不会继承终端变量，让 Cursor 进程能读到 `BEATAPI_API_KEY` 后再重启 Cursor。已有 MCP 配置文件时，把 `beatapi` 这一项合并进已有文件。

### Claude Code

在项目的 `.mcp.json` 添加下面的配置。进入项目会话后，用 `/mcp` 查看 `beatapi` 的连接和工具；Claude Code 提示批准项目工具时，先核对服务地址再批准。

```json
{
  "mcpServers": {
    "beatapi": {
      "type": "http",
      "url": "https://beatapi.io/mcp",
      "headers": {"Authorization": "Bearer ${BEATAPI_API_KEY}"}
    }
  }
}
```

### Cursor

单个项目用 `.cursor/mcp.json`，个人账号级用 `~/.cursor/mcp.json`。在 Cursor 的 MCP 设置里确认 `beatapi` 服务已启用，并在 Agent 中确认 `beatapi` 的工具可用。

```json
{
  "mcpServers": {
    "beatapi": {
      "url": "https://beatapi.io/mcp",
      "headers": {"Authorization": "Bearer ${env:BEATAPI_API_KEY}"}
    }
  }
}
```

### Codex CLI

把下面的配置加到 `~/.codex/config.toml`。启动新的 Codex 会话后输入 `/mcp` 查看已加载的工具。

```toml
[mcp_servers.beatapi]
url = "https://beatapi.io/mcp"
bearer_token_env_var = "BEATAPI_API_KEY"
```

## 从工具列表到研究材料

1. **检查连接。** 确认工具列表里有 `capabilities_search`、`capabilities_inspect` 和 `capabilities_run`。让助手用 `capabilities_search` 搜「小红书 搜索笔记」，把返回的 `reference` 原样传给 `capabilities_inspect`，查看必填输入、价格和就绪状态。连接检查到这一步结束。
2. **查一页。** 准备取材时，让助手按一个关键词只搜一页，并先说明要传的参数和价格。返回的是预览时，记录请求号、`items_path` 和预览的实际范围。保留这次的结果，挑一条有来源的笔记，再决定是否补读这条笔记的评论。
3. **加其他平台。** 做跨平台对照时，抖音用[综合搜索](/zh/guides/douyin-python-research)找视频；公众号有已核对的账号时，先查这个账号的[文章目录](/zh/guides/wechat-incremental-articles)，有具体文章链接时按需读正文。每个来源记录动作、对象 ID、原文链接和材料类型。

首次提示示例：

> 先找小红书关键词搜索能力，告诉我一页查询的输入和价格。等我指定要查的词后，只查一页。给出实际看到的候选、来源和是否需要看评论。只看到摘录时标记为摘录。

经常做同一类选题时，把筛选规则和交付字段写进自己客户端的任务 Skill，工具说明以 [BeatAPI Skill](https://beatapi.io/skill.md) 为准。再次查询前，先复用已保存、且已经包含所需证据的结果。

## 第一次查询后，怎样判断结果能不能用？

* **看到工具和价格。** 助手能列出小红书关键词搜索的必填参数和价格，说明工具入口可用。接下来再提供你要查的词。
* **拿到可以复查的线索。** 比如预览里有一条标题为《除垢后还是有异味》的笔记，让助手在同一行写出返回的笔记 ID、请求号和材料类型「搜索摘录」。之后打开原文或补读这条笔记的详情时，就能按这一行找到来源。
* **只看到前几条。** 对照 `items_total` 和展示的条数。要看本次查询已经返回的其他条目，用同一个 `reference` 和 `request_id` 读取已保存结果，响应里有 `next` 指引时照做。需要更多结果时才另查新的一页。

[BeatAPI 预览和结果读取说明](https://beatapi.io/skill-refs/run.md)

例如预览显示 3 条，`items_total` 是 20。要选第二个对照案例，打开已保存的结果，在返回的 20 条笔记里按笔记 ID 挑选。这 20 条里没有你要的机型时，再查平台下一页，或换一个带机型名的关键词。简报里记录实际读了哪一批、选了哪一条。

## 连接或结果出问题时查哪里？

| 现象          | 核对                                     |
| ----------- | -------------------------------------- |
| 服务找不到或工具没显示 | 当前配置文件、进程变量、项目批准状态和远程 HTTP 类型          |
| 返回 401      | Bearer 头是否随客户端请求发送，以及密钥在 BeatAPI 中是否有效 |
| 工具可列出但调用失败  | 看工具结果的错误和请求号，按 Inspect 的输入合同检查         |
| 结果只有截断条目    | 检查预览范围，需要完整材料时读取同一次结果，再考虑下一页           |

新页、笔记详情和评论分别按请求计费，见 [BeatAPI 价格页](https://beatapi.io/zh/pricing)。响应路径和翻页方式见[小红书搜索导出](/zh/guides/xiaohongshu-notes-research)和[小红书评论](/zh/guides/xiaohongshu-note-comments)。

[BeatAPI 接入说明](https://beatapi.io/skill-refs/setup.md) · [Claude Code MCP 文档](https://code.claude.com/docs/en/mcp) · [Cursor MCP 文档](https://cursor.com/docs/mcp)