Skip to content

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.

Get an API key

Included with Pro and Ultra. The same key works for the REST API and the MCP server.

Connect Claude, Cursor or any MCP client

SettingValue
Server URLhttps://api.hearbuyers.com/mcp
TransportStreamable HTTP, stateless, JSON responses
AuthenticationAuthorization: Bearer hb_live_YOUR_KEY
ScopeThe 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).

ToolWhat it doesREST route
find_buyersLists matches, newest post firstGET /v1/matches
get_matchOne match in full: the post, the author, why it matched, drafts and historyGET /v1/matches/{id}
update_matchMoves a match to a stage, or marks it not relevant with a reasonPATCH /v1/matches/{id}
draft_replyWrites a fresh reply, DM or email (author's public address) draft. Nothing is postedPOST /v1/matches/{id}/drafts
list_listenersWhat the project listens for, with plan usageGET /v1/listeners
add_listenerAdds something to listen for and asks for a scanPOST /v1/listeners
remove_listenerRemoves a listener. Its matches stayDELETE /v1/listeners/{id}
list_leadsPeople who showed buying intent, one row per authorGET /v1/leads
brand_signalsMentions of the project and its competitors, with share of voice and sentimentGET /v1/brand-signals
overviewBuyers found, replied, won and what is waitingGET /v1/overview

Tool inputs

Inputs marked (required) must be sent. Everything else is optional.

ToolInputs
find_buyersstage (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_matchid (required)
update_matchid (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_replyid (required), kind (reply by default, dm, or email when the author put an address in their public X bio)
list_listenersnone
add_listenertype (required: keywords, subreddit, x_account, x_mentions, tweet_replies, reddit_thread or competitor), name, sources, terms, target, excludeWords
remove_listenerid (required)
list_leadsplatform (x or reddit), q, limit (up to 200, default 50), offset
brand_signalsdays (default 30), brand, sentiment (positive, neutral or negative)
overviewdays (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.email is filled. Asking for an email on any other match returns an error with draft_failed, and asking again gets the same answer. A dm works 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_inactive answer before any tool runs.
  • When a tool fails, the result has isError set 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.