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

| 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 — 44 tools

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

| Area | Tools | |---|---| | Messaging | send_message (with reply_to to quote) · send_media · send_poll · get_poll_results · send_location · send_contact | | Conversational signals | react_message (emoji: "" removes) · mark_read · send_typing — free on every tier; they consume no send budget and don't raise the risk score | | Memory & reading | get_ai_context (role-mapped memory feed) · search_messages · fetch_new_messages (poll cursor) · list_chats | | Vision (see what people send) | 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 | | 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 & batches (Pro) | queue_import — for people already waiting on you: one {{field}} template + up to 5000 rows, each row becoming one individual, personalised message paced by anti-ban · queue_message (one, scheduled) · queue_status · list_queue · cancel_queued · retry_queued · list_batches · 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'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:

| 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 | | scope_boundaries | orders, opening hours and the menu | | additional_rules | anything extra |

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:

| 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) | — | ✅ |

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.