socialmate-mcp

A native Model Context Protocol server for SocialMate — the self-hosted WhatsApp automation server (desktop app, or headless on your own VPS/Docker, managed from a browser at /admin). Point Claude Desktop, Cursor, Cline or any MCP client at it and your agent can send and read WhatsApp messages, look up contacts, manage groups, queue a paced batch of personalised messages, recall whole conversations, look at the photos people send, remember who it's talking to and what media said, and check anti-ban headroom — 44 tools, all on your own machine and your own number.

SocialMate doesn't contain an AI — it gives your AI a WhatsApp. This server is a thin translator over SocialMate's local REST API: every tool call runs through the app's real auth → scope → tier-gate → anti-ban → audit pipeline, so nothing here can bypass a limit and the app stays the single source of truth.

• Guide: https://socialmate.app/docs/mcp-server

• Landing page: https://socialmate.app/whatsapp-mcp-server

• The app: https://socialmate.app

Requirements

• SocialMate running — either the desktop app or a headless VPS/Docker install. Point SOCIALMATE_BASE_URL at whichever you run; the tools are identical.

• Its local API server switched on. ⚠️ It is off by default — turn it on in API & Integrations. This is the single most common reason the tools don't show up: the MCP server starts fine, then has nothing to talk to.

• An API key from the app (API & Integrations → API Keys → new key). Its scope (read / send / admin) and your license tier decide which tools work.

• Node.js ≥ 18.17 (only to run npx — there is nothing to install globally; npx fetches this package on first run).

Quickstart — Claude Desktop, Cursor, Cline

Add SocialMate to your claude_desktop_config.json (the app shows this 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"
      }
    }
  }
}

Restart Claude Desktop and the WhatsApp tools appear. Cursor, Cline, Goose and any other MCP client use the same command / args / env — drop it into their MCP config the same way.

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

Quickstart — 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. Ask it to call whatsapp_get_capabilities first — that tells the agent its tier, scope and feature flags, so it knows what it's allowed to do before it tries.

Environment variables

What your agent can do — 44 tools

All namespaced whatsapp_*; the model picks the right one from its description.

Account-scoped tools take an optional account_id; with a single-account key it's auto-resolved. 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.

The table lists 43. The 44th is whatsapp_get_conversation, a deprecated alias of whatsapp_get_ai_context — still served so existing agents don't break, but not worth teaching a new one.

The vision loop. list_media (has_context: false) → get_media (the item comes back as a real image content block your vision model can see) → set_media_context (cache the description). After that the photo rides along already described inside get_ai_context, and is never analyzed again. get_media returns the thumbnail — enough to see what a photo is, bounded in size; the full-resolution bytes stay on the HTTP API on purpose (see below).

Batch sending is off by default. queue_import returns 403 bulk_import_disabled (the wire code is unchanged) until the user switches it on in the app (Settings → Advanced → "Enable batch sending"). SocialMate is not a broadcast tool — it is for managing your own conversations, with people who are already waiting on you. Every batch item is an individual, personalised message paced by the anti-ban engine; identical text to many contacts is blocked by the duplicate guard. When the gate is closed the server tells the agent to ask, rather than to loop send_message — which is the pattern that gets numbers banned.

Deliberately not exposed: API-key management, webhook wiring, the per-account proxy, media writes (force-download / delete / cleanup), and the raw media file — an agent minting keys, rewiring delivery, re-routing traffic, deleting files, or pulling a 15 MB blob into its context is a footgun. Do those in the app, or over the HTTP API / n8n. The full list, with a reason per endpoint, is the NOT_EXPOSED allowlist in contract.test.mjs — a new app endpoint fails the build until it is either given a tool or deliberately skipped there.

🧠 A seed prompt that makes the agent behave like a human

The server ships a native MCP prompt — socialmate_human_agent — so any client that supports prompts/list (Claude Desktop, Cursor, …) can load it as a system prompt. No copy-paste.

It teaches the human reply cadence (mark read → recall the thread → show typing → react or reply), the whole tool inventory and when not to use each, the tier + anti-ban error contract (402, blocked sends, queueable:false, signal_rate_limit), the things the agent genuinely cannot do (no edit/delete/forward; it can't see the contact typing; buttons are deprecated — send a poll), and the consent and honesty rules.

Fill it in with your business:

You don't need to copy it — the server serves it natively. The canonical text (and the n8n variant) is published at https://socialmate.app/docs/ai-agent-prompt.

Reactions, read receipts and the typing indicator are free on every tier and consume no send budget — an agent can behave like a human without spending its message allowance.

📥 Reacting to incoming messages

This is the one thing to know about MCP. MCP is request/response — it has no inbound push. The server can't notify Claude/Cursor that a WhatsApp message just arrived; a client only acts when you ask it to. Two ways to make an agent react to messages as they arrive:

1. Poll (pure MCP) — call whatsapp_fetch_new_messages on a loop, passing the newest timestamp you've seen as since to get only what's new. Requires Pro (it reads synced history).

2. Event-driven (bridge) — start the loop from n8n's SocialMate Trigger (message.received) or a webhook to your own code, then let the agent act back through these tools. Works on Free too (the message.received webhook is a Free event).

For a desktop assistant you drive by hand, MCP alone is perfect. For an unattended auto-responder, use the bridge.

Did it land? — delivery receipts

Every message row returned by whatsapp_fetch_new_messages and whatsapp_search_messages carries a status: pending → sent → delivered (it reached their phone) → read (they opened it). So an agent can check whether something it sent actually landed by re-reading the row — it never has to ask a human. Note that a send returns status: "sent", which only means handed to WhatsApp; it is not proof of arrival.

To be told the moment it lands, subscribe to the two receipt webhooks (Pro) — like every other event, they arrive through the n8n SocialMate Trigger or your own receiver, never over MCP:

Both carry messageId, status and fromMe: true — correlate on the messageId your send returned and the notification loop closes. They fire only for messages the operator sent: an inbound message the operator reads on their own phone never emits one, so message.read always means they read yours, never you read theirs.

Scope & tiers

Tools honor the API key's scope and your license tier, exactly like the REST API:

A gated tool returns a clear "requires Pro" error rather than failing silently, so the agent can adapt (e.g. fall back to a plain text send).

Develop / explore

Browse and call every tool interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector npx -y socialmate-mcp

Run the test suite (spawns the server against a mock REST API and drives it over MCP):

npm install
npm test

Prefer n8n?

Building visual, triggered workflows instead of a desktop assistant? SocialMate also ships a native n8n node whose every operation is usable as an AI-Agent tool. Same WhatsApp, different client — see the AI agents guide.

License

MIT © SocialMate Ltd.