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 ). 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
Estrelas
—
Ferramentas
—
Disponibilidade
—
/admin
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.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Socialmate?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Socialmate precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Socialmate usa?
Socialmate roda localmente via stdio.
Quando Socialmate foi verificado pela última vez?
Última verificação: 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.