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
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, , remember who it's talking to and what media said, check anti-ban headroom, and
supervise SocialMate's built-in (Pro) —
, all on your own machine and your own number.
Model Context Protocol server for SocialMate — let Claude Desktop, Cursor and any MCP client control WhatsApp through your self-hosted SocialMate server.
2026-11-16
星數
—
工具
—
可用率
—
Claude Desktop, Cursor, Cline
look at the
photos people send
Claude Agent
59 tools
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.
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):
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.
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
Variable
Required
Default
What it is
SOCIALMATE_API_KEY
✅
—
An API key from the app → API & Integrations.
SOCIALMATE_BASE_URL
http://127.0.0.1:3456
The app's API — a desktop app or a headless VPS. Use your Pro named tunnel host to drive WhatsApp from a remote agent. On a VPS (a datacenter IP) you can route an account through your own residential/mobile proxy (Pro) to keep a residential IP.
What your agent can do — 59 tools
All namespaced whatsapp_*; the model picks the right one from its description.
list_media (has_context: false = "what haven't I looked at yet?") · get_media — returns the image as an MCP image block, so your model can actually look at it · set_media_context — save what you saw, so it's never analyzed twice
Agent Memory (write, Pro)
update_contact (save a name/notes/tags you learned) · set_media_context — SocialMate stores what your agent learned, it never generates it
Agent (Pro) — supervise SocialMate's built-in Claude Agent
agent_list · agent_get · agent_pause · agent_resume · agent_usage · agent_usage_summary · agent_list_approvals · agent_decide_approval · agent_list_handoffs · agent_take_over · agent_release · agent_reply (a human reply, sent as you, that keeps the agent out of that chat) · agent_send_event (start an event job — order update, booking reminder… — for a customer from your own records) · agent_list_knowledge · agent_add_knowledge
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_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:
Argument
Example
business_name
Northwind Coffee
business_description
specialty coffee roastery in Cairo
agent_name
Nora
agent_role
front-desk support
tone
warm, concise, never salesy
business_hours
Sun–Thu, 9:00–17:00 Cairo time
escalation_procedure
tagging @ops in Slack and telling the customer a colleague will follow up
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_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).
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:
Event
Fires when
message.delivered
Your message reached the recipient's phone (two grey ticks)
message.read
They opened it (two blue ticks)
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:
Free
Pro
Read messages, chats, contacts, groups
✅
✅
Send text
✅
✅
Anti-ban status, capabilities
✅
✅
Send media, create/manage groups
—
✅
History, Get AI Context, poll cursor
—
✅
Smart queue (schedule / batch / control)
—
✅
Supervise SocialMate's Claude Agent (whatsapp_agent_*)
—
✅
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:
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.
Model Context Protocol server for SocialMate — let Claude Desktop, Cursor and any MCP client control WhatsApp through your self-hosted SocialMate server.
上次檢查時間:2026-11-16。 Model Context Protocol server for SocialMate — let Claude Desktop, Cursor and any MCP client control WhatsApp through your self-hosted SocialMate server.