Connect Claude Code, Cursor or Codex to BeatAPI social data
Add BeatAPI as a remote MCP server named beatapi in Claude Code, Cursor or Codex, with BEATAPI_API_KEY supplied from the environment. Public lookups need only the BeatAPI key, not Xiaohongshu cookies. After setup, the agent has three tools: capabilities_search finds an action, capabilities_inspect shows the action’s inputs, price and readiness, and capabilities_run executes the action. As a first task, ask the agent to search one Xiaohongshu page for “coffee machine descaling” and shortlist notes worth opening. Search Douyin when you need a video demonstration, and fetch a WeChat article’s text when you have the article URL.
Configure your client
Provide BEATAPI_API_KEY through the client process environment or the client’s credential settings; the examples below reference the variable name only. A desktop app may start outside your shell environment, so restart Cursor after making BEATAPI_API_KEY available to the Cursor process. If an MCP configuration file already exists, merge the beatapi entry into the existing file.
Claude Code
Add the following to your project’s .mcp.json. In a project session, open /mcp to see the beatapi connection and tools. If Claude Code asks for project approval, verify the server address before approving.
Cursor
Use .cursor/mcp.json for one project or ~/.cursor/mcp.json for your account. In Cursor’s MCP settings, confirm that the beatapi server is enabled and that the beatapi tools are available in Agent.
Codex CLI
Add the block below to ~/.codex/config.toml. Start a new Codex session and use /mcp to inspect the loaded tools.
Collect a first batch
- Check the connection. Look for
capabilities_search,capabilities_inspectandcapabilities_runin the tool list. Ask the agent to find Xiaohongshu keyword search withcapabilities_search, then pass the exact returnedreferencetocapabilities_inspectto see the required inputs, price and readiness. The connection check ends at this step. - Search one page. When you are ready to gather evidence, send one keyword and search one page. When the response is a preview, record the request ID,
items_pathand the observed scope of the preview. Keep the saved response. Select one relevant note with a source before deciding whether to fetch the note’s comments. - Add other platforms. Use Douyin keyword search for videos. With a verified WeChat account, start with the account’s article list; with one article URL, fetch the article body if needed. For each source, keep the action, object ID, original link and material type.
Example first prompt:
Find Xiaohongshu keyword search and show the inputs and price for one page. Once I choose the keyword, fetch one page. Give me the actual candidates and sources, then flag any that merit reading the comments. Label excerpts as excerpts.
For recurring research, save your review criteria and output columns in a task Skill for your client, and use the BeatAPI Skill for tool instructions. Before querying again, reuse saved results that already contain the evidence you need.
How do you know the first lookup gave you something usable?
- The tool and price are visible. When the agent lists the required inputs and price for Xiaohongshu keyword search, the tool entry point works. Then supply the term you want to search.
- You have a lead you can check. When a preview shows a note titled “My machine still smells after descaling,” ask the agent to put the returned note ID, request ID and material type (“search excerpt”) on the same row. The row lets you trace the source or fetch the selected note later.
- Only the first few items are visible. Compare
items_totalwith the number of items shown. To see other items the lookup already returned, read the saved result with the samereferenceandrequest_id, following the response’snextinstructions when present. Request a new page only when you need additional results.
BeatAPI preview and result retrieval
For example, the preview shows three items and items_total is 20. To pick a second example, open the saved result and choose from the 20 returned notes by note ID. If the 20 notes do not cover the machine model you need, request the next platform page or run a more specific search. In the brief, record the batch you reviewed and the note you selected.
Troubleshoot the connection and results
Extra pages, note details and comment requests are billed as separate requests; see BeatAPI pricing. The note search and comment research guides give the response paths and paging.

