SocialMate Local API

MCP server (Claude, Cursor)

Connect WhatsApp to Claude Desktop, Cursor or any MCP client — the socialmate-mcp config, the full tool catalogue, and how an agent reacts to incoming messages.

SocialMate speaks the open Model Context Protocol. Its native socialmate-mcp server lets Claude Desktop, Cursor, Cline — any MCP client — control WhatsApp as native tools: send and read messages, look up contacts, manage groups, queue batches of personalised messages, recall whole conversations and check anti-ban headroom. It runs on your own machine with your own number, and it is a thin translator over the same local REST API the rest of this documentation covers — so every tool call flows through the app's real auth → scope → tier-gate → anti-ban → audit pipeline. Nothing an agent does through MCP can bypass a limit.

MCP or the n8n node — same WhatsApp, different client. Use MCP for a desktop assistant (Claude Desktop, Cursor) or any MCP-native agent. Use the n8n node to build visual, triggered workflows. Both expose the same operations; both are the WhatsApp tool your AI uses.

Set it up in two minutes

Turn on the local API server. In the SocialMate app → API & Integrations, switch it on — it is off by default. MCP is a translator over that local API, so until it is running your client will connect, list the tools, and fail every call. This is the single most common reason the WhatsApp tools don’t work. (Quickstart walks through it.)
In the same place → API Keys, create an API key. Its scope (read / send / admin) and your license tier decide which tools work — Free covers read and plain-text send; Pro adds media, history, Get AI Context and the queue. Copy it now: it is shown once.
Add SocialMate to your MCP client (below), then restart the client. There is nothing to install — npx fetches socialmate-mcp from npm on first run. You just need Node.js 18.17+.

Claude Desktop, Cursor, Cline

Add this to claude_desktop_config.json (the app shows the same snippet with your real URL already filled in, under API & Integrations → MCP):

{
  "mcpServers": {
    "socialmate": {
      "command": "npx",
      "args": ["-y", "socialmate-mcp"],
      "env": {
        "SOCIALMATE_API_KEY": "sm_paste_your_api_key_here",
        "SOCIALMATE_BASE_URL": "http://127.0.0.1:3456"
      }
    }
  }
}

Claude Code

Same server, one command:

claude mcp add socialmate \
  --env SOCIALMATE_API_KEY=sm_paste_your_api_key_here \
  --env SOCIALMATE_BASE_URL=http://127.0.0.1:3456 \
  -- npx -y socialmate-mcp

Then claude mcp list to confirm it connected.

Keep the -y. Without it, npx can stop to ask you to confirm the install — inside an MCP client, where there is no terminal to answer it, so the server simply never starts.

Restart the client and the WhatsApp tools appear. SOCIALMATE_BASE_URL defaults to http://127.0.0.1:3456 (the app on the same machine). To drive WhatsApp from a remote agent, point it at your Pro named tunnel host instead — the same x-api-key auth applies over the wire. The server itself always runs locally over stdio; there is no remote MCP endpoint to point at.

The tool catalogue

44 tools, all namespaced whatsapp_*. An agent picks the right one from its description:

Area	Tools
Messaging	`send_message` (with `reply_to` to quote), `send_media`, `send_poll`, `send_location`, `send_contact`, `queue_message`
Conversational signals	`react_message` (empty emoji removes), `mark_read`, `send_typing` — free on every tier; they consume no send budget and don’t raise the anti-ban risk score
Memory & reading	`get_ai_context` (role-mapped memory feed, with reactions + poll results inlined), `get_conversation`, `get_poll_results` (tally + who voted), `search_messages`, `fetch_new_messages` (poll cursor), `list_chats`
Media	`list_media`, `get_media`
Agent Memory (write, Pro)	`update_contact` (save a name/notes/tags you learned) · `set_media_context` (cache a photo/voice-note description so it’s never re-analyzed) — SocialMate stores what your agent learned, it never generates it
Contacts	`list_contacts`, `get_contact`
Groups	`list_groups`, `get_group`, `create_group`, `update_group_participants`, `set_group_subject`, `set_group_description`, `get_group_invite`, `leave_group`
Queue	`queue_status`, `queue_import` (queue a batch of individually personalised messages), `list_queue`, `list_batches`, `cancel_queued`, `retry_queued`, `cancel_batch`, `retry_batch`, `pause_queue`, `resume_queue`
Sync & status	`trigger_sync`, `sync_status`, `get_antiban_status`, `get_capabilities`, `list_accounts`

Account-scoped tools take an optional account_id; with a single-account key it is auto-resolved. API-key management and webhook wiring are deliberately not exposed — an agent minting keys or rewiring delivery is a footgun, so you do those in the app. A good first call is whatsapp_get_capabilities: it tells the agent its tier, scope and feature flags so it knows what it's allowed to do before it tries.

How an agent reacts to incoming messages

This is the one thing to understand about MCP. MCP is request/response — it has no inbound push. The server cannot notify Claude or Cursor that a WhatsApp message just arrived; a client only acts when you ask it to (“message Jordan the address”). There are two ways to make an agent react to messages as they arrive:

1 · Poll (pure MCP)

Call whatsapp_fetch_new_messages on a loop
Pass the newest timestamp you've seen as since — you get only what's new
No extra infrastructure; works inside a single agent loop
Pro — it reads the synced history archive

2 · Event-driven (bridge)

Start the loop from n8n's SocialMate Trigger (message.received) or a webhook to your own code
Your code/LLM handles the event, then acts back through the MCP tools
True push — no polling delay
Works on Free too — message.received is a Free webhook event

In short: for a desktop assistant you drive by hand, MCP alone is perfect. For an unattended auto-responder, drive the trigger from the SocialMate Trigger or a webhook and let the agent act back through MCP.

Bring your own brain. SocialMate provides WhatsApp as tools and memory, not the model. AI generation (replies, summaries) inside SocialMate itself is “coming soon” and isn't shipped — you stay in control of which LLM you use, your prompts and your costs.

Tiers. Free MCP covers reading and plain-text sending. Media, the message archive, Get AI Context, the poll cursor and the queue are Pro — the agent gets a clear “requires Pro” error on a gated tool rather than a silent failure. Compare plans →

Explore the tools

Point the MCP Inspector at the server to browse and call every tool interactively:

npx @modelcontextprotocol/inspector npx -y socialmate-mcp

Prefer a visual, triggered workflow? See the WhatsApp MCP server overview or the n8n AI agents guide.