Twitter MCP server for finding buyers on X and Reddit
updated 13 November 2026
The HearBuyers MCP server lets an AI client work through your buyers on X and Reddit. Ask Claude or Cursor who is asking for what you sell, have it read a match in full and draft the reply, then move the match along once you've answered.
It isn't a general X MCP or an MCP Twitter search tool, and it can't search every tweet. It works on your own project: the matches HearBuyers found for the phrases, subreddits, accounts and competitors you listen for, each scored for buying intent. Connect it with the Streamable HTTP address below and a key from your project. It runs on the same code as the REST API.
Included with Pro and Ultra. The same key works for the REST API and the MCP server.
Connect Claude, Cursor or any MCP client
| Setting | Value |
|---|---|
| Server URL | https://api.hearbuyers.com/mcp |
| Transport | Streamable HTTP, stateless, JSON responses |
| Authentication | Authorization: Bearer hb_live_YOUR_KEY |
| Scope | The one project the key belongs to |
Make the key on the API page of your project, then pick your client.
Claude code
Run this in a terminal:
claude mcp add --transport http hearbuyers https://api.hearbuyers.com/mcp \
--header "Authorization: Bearer hb_live_YOUR_KEY"Claude Desktop
Open Settings, Developer, Edit config, and add this to claude_desktop_config.json. Restart Claude afterwards. It uses mcp-remote to reach a remote server.
{
"mcpServers": {
"hearbuyers": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.hearbuyers.com/mcp",
"--header",
"Authorization:Bearer hb_live_YOUR_KEY"
]
}
}
}Cursor
Open Settings, MCP, Add new server, or put this in ~/.cursor/mcp.json:
{
"mcpServers": {
"hearbuyers": {
"url": "https://api.hearbuyers.com/mcp",
"headers": {
"Authorization": "Bearer hb_live_YOUR_KEY"
}
}
}
}Any other client that supports Streamable HTTP with custom headers can use the same URL and header.
Tools
The server has ten tools. Each one calls the REST route listed beside it, so it returns what that route returns and follows the same rules, with one difference: a number you set to 0 is left out of the call (see minScore below).
| Tool | What it does | REST route |
|---|---|---|
find_buyers | Lists matches, newest post first | GET /v1/matches |
get_match | One match in full: the post, the author, why it matched, drafts and history | GET /v1/matches/{id} |
update_match | Moves a match to a stage, or marks it not relevant with a reason | PATCH /v1/matches/{id} |
draft_reply | Writes a fresh reply, DM or email (author's public address) draft. Nothing is posted | POST /v1/matches/{id}/drafts |
list_listeners | What the project listens for, with plan usage | GET /v1/listeners |
add_listener | Adds something to listen for and asks for a scan | POST /v1/listeners |
remove_listener | Removes a listener. Its matches stay | DELETE /v1/listeners/{id} |
list_leads | People who showed buying intent, one row per author | GET /v1/leads |
brand_signals | Mentions of the project and its competitors, with share of voice and sentiment | GET /v1/brand-signals |
overview | Buyers found, replied, won and what is waiting | GET /v1/overview |
Tool inputs
Inputs marked (required) must be sent. Everything else is optional.
| Tool | Inputs |
|---|---|
find_buyers | stage (open by default, or replied, won, not_a_fit, dismissed, closed, all), source (x or reddit), minScore (0 to 100, defaults to the project's threshold), since (RFC 3339 time), limit (up to 100, default 50), cursor (the nextCursor of the last call) |
get_match | id (required) |
update_match | id (required), then stage (open, replied, won, not_a_fit or dismissed) or feedback (not_a_buyer, wrong_topic, self_promo, vendor or other) with an optional note |
draft_reply | id (required), kind (reply by default, dm, or email when the author put an address in their public X bio) |
list_listeners | none |
add_listener | type (required: keywords, subreddit, x_account, x_mentions, tweet_replies, reddit_thread or competitor), name, sources, terms, target, excludeWords |
remove_listener | id (required) |
list_leads | platform (x or reddit), q, limit (up to 200, default 50), offset |
brand_signals | days (default 30), brand, sentiment (positive, neutral or negative) |
overview | days (default 30) |
One input behaves in a way you might not expect:
- `draft_reply` can't write every kind. An email exists only when
author.emailis filled. Asking for an email on any other match returns an error withdraft_failed, and asking again gets the same answer. Admworks for X and Reddit matches and writes only the DM. The rules are in Draft a reply, DM or email.
minScore takes 0 to 100. Send 0 to list every match, or leave it out to use the project's threshold, which is 70 unless you changed it.
The REST API page explains each field and shows the response.
Try these prompts
Once the server is connected, ask in plain words:
- "Show my open buyers with a score above 85 from the last three days, and tell me which one to answer first."
- "Open the top match, read the whole post and draft a short reply that answers their question."
- "Mark that match as replied. Then mark the self-promotion post as not relevant, with the reason vendor."
- "Add a listener for people switching from a competitor of ours, on Reddit and X."
- "How many buyers did we find this week, and how is our share of voice against the competitors?"
An AI client can read and change the project with your key. Give it a key for the project it should work on, and revoke the key when you're done. Nothing is ever posted to Reddit or X from here.
Limits and errors
Every tool call runs the matching REST route, so it counts against the rate limit of the key you connected with. Pro allows 60 requests a minute and Ultra allows 300. Connecting and listing the tools don't count.
- A missing or revoked key gets a 401 when the client connects.
- A project without a live plan gets a 402
plan_inactiveanswer before any tool runs. - When a tool fails, the result has
isErrorset to true and carries the same JSON body the REST route would return, such as{"error":"match not found"}. The client passes that text to the model, which can often fix the request itself.
Check it by hand
You can talk to the server without a client by sending the headers a Streamable HTTP client sends, including Accept: application/json, text/event-stream.
curl -X POST "https://api.hearbuyers.com/mcp" \
-H "Authorization: Bearer hb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "overview", "arguments": {"days": 1}}}'A tool result is JSON-RPC with the REST body as text. This one comes from a test project with made-up posts:
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"daily\":[{\"date\":\"2026-11-13\",\"found\":2,\"replied\":1}],\"days\":1,\"found\":{\"reddit\":1,\"total\":2,\"x\":1},\"lastScanAt\":null,\"replied\":1,\"stillUp\":0,\"waiting\":{\"approvedNotPosted\":0,\"newLeads\":3,\"open\":2},\"won\":0}"}]}}Use tools/list instead of tools/call to read every tool and its input schema.
Questions about the Twitter MCP server
Can it search any tweet?
No. It reads the matches HearBuyers found for your project, so what you get depends on your listeners. To search X by hand, use the free X search builder.
Can it post to X or Reddit?
No. The tools read matches, change their stage, manage listeners and write draft text. A person posts the reply.
Which plans include it?
Both Pro and Ultra; see pricing. The MCP server uses the same keys and rate limits as the REST API.
What if my client only supports local servers?
Use mcp-remote, as in the Claude Desktop example. It runs on your machine and forwards to the HearBuyers server over HTTPS.
Can I find buyers on Reddit this way too?
Yes. Every match says whether it came from X or Reddit, and find_buyers takes a source filter. For the Reddit side of the product, read about Reddit lead generation.
Get an API key
Keys are on your project's API page. The API, the MCP server and webhooks come with Pro and Ultra, so start the 7-day trial first. Pro allows 60 requests a minute per key, and Ultra allows 300.