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, check anti-ban headroom, and
supervise SocialMate's built-in Claude Agent (Pro) —
59 tools, all on your own machine and your own number.
This server doesn't add an AI — it gives your AI a WhatsApp. (SocialMate Pro also has its own built-in WhatsApp agent; the
whatsapp_agent_*tools let yours supervise it.) 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_URLat 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;npxfetches 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 itnpxcan 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 — 59 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 58. The 59th 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.
SocialMate's own agent — the Claude Agent. The whatsapp_agent_* tools supervise the WhatsApp AI agent
built into the SocialMate app (Pro). It is built on Anthropic's Claude Agent SDK; the model is the owner's choice. With these tools you can pause it, answer what it is holding for approval, take a chat over and
reply as yourself, hand it back, feed it a business event or a fact. The agent itself — its AI
provider, persona, jobs and autonomy — is created and configured in the SocialMate app, not over MCP.
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), the raw media file, and the native agent's setup (creating, configuring or deleting an agent, AI provider keys, senses, the WordPress pairing) — an agent minting keys, rewiring delivery, re-routing traffic, deleting files, rewriting another agent's instructions, 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_EXPOSEDallowlist incontract.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:
- Poll (pure MCP) — call
whatsapp_fetch_new_messageson a loop, passing the newesttimestampyou've seen assinceto get only what's new. Requires Pro (it reads synced history). - 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 (themessage.receivedwebhook 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.
