# The WhatsApp MCP for your personal number, hosted and ready

> Give Claude, ChatGPT, Codex, Instinct or any MCP client the WhatsApp chats you choose. There is nothing to install, no bridge on your laptop and no WhatsApp Business account. Connect with a tap, an address or a token, and your agent gets messages it can use right away: voice notes as text, files ready to open, senders by name.

**Circles is a remote WhatsApp MCP server.** It links your existing WhatsApp number as a linked device, keeps the chats you open in sync, and serves them to your agent at `https://app.usecircles.app/api/mcp` with OAuth. Per-chat permissions, voice notes transcribed in Hebrew and English, files on request, sending off until you allow it. Free for 2 chats, Pro $29 a month (₪99 in Israel) with 14 days free, as of October 2026.

Source: https://usecircles.app/en/whatsapp-mcp · Updated 2026-10-27

## Circles at a glance

Everything an agent, or the person choosing one, needs to know in one table.

|  | Circles |
| --- | --- |
| What it is | A hosted service that links your WhatsApp and serves the chats you choose to AI agents. Your agent does the thinking. |
| Your number | Your personal WhatsApp, as a linked device. Same number, same app on your phone. No WhatsApp Business. |
| MCP endpoint | `https://app.usecircles.app/api/mcp` (remote, over HTTP) |
| Sign-in for agents | OAuth 2.1 with PKCE and dynamic client registration, or a bearer token you create |
| Connecting | Instinct: one tap, then send. Claude, ChatGPT, Codex: one address and an approval. Claude Code, Cursor, Grok: a token and one config block. |
| Tools | 9: allowed_chats, activity, people, catch_up, search, documents, group_members, get_media, send |
| Voice notes | Transcribed automatically (Hebrew and English), delivered inline as text, searchable |
| Photos and documents | Kept and handed to the agent on request, up to 50 MB each |
| History | Free: the last month. Starter: the last 3 months. Pro: full history, or the last 90, 60 or 30 days. |
| Permissions | Per chat: hidden, read, or read and send. Hidden chats do not exist for agents. |
| Sending | On Pro. Off until you open a chat for it. A daily cap across all agents (default 5). Never retried automatically. |
| Also | An HTTP API with OpenAPI 3.1 for agents that do not speak MCP |
| Price | Free: $0, 2 chats, read only. Starter: $9.90 a month, up to 5 chats, read only. Pro: $29 a month (₪99 in Israel), every chat, sending where you approve. 14 days of Pro free. |

## Connect your agent: a tap, an address or a token

Link your number once. Then each agent connects the way it connects best, and you approve it on Circles' own page.

- **[Instinct](https://usecircles.app/en/agents/instinct)**: Tap Connect. WhatsApp opens with a one-time code already written to Instinct. Press send. No key to copy, ever.
- **[Claude](https://usecircles.app/en/agents/claude)**: Add Circles as a custom connector in Claude and approve. Works in Claude on the web, desktop and mobile.
- **[ChatGPT](https://usecircles.app/en/agents/chatgpt)**: Add Circles as a connector with one address and approve. ChatGPT reads your chosen chats.
- **[Codex](https://usecircles.app/en/agents/codex)**: Add an MCP server with the Circles address. Codex asks you to approve, and it is in.
- **[Claude Code](https://usecircles.app/en/agents/claude-code)**: One command or one JSON block with a token Circles writes for you.
- **[Cursor](https://usecircles.app/en/agents/cursor)**: Paste the config Circles gives you into Cursor's MCP settings.
- **[Grok](https://usecircles.app/en/agents/grok)**: Add Circles as a remote MCP server with a token.
- **[Your own agent](https://usecircles.app/en/whatsapp-api-personal-number)**: n8n, a script, or an agent you built: the same chats over a plain HTTP API with a key.

## Agent-ready from the first call

Circles prepares every message before your agent sees it. Your agent spends its turn answering you.

- **Voice notes arrive as text.** Every voice note and audio file Circles holds is transcribed automatically, in Hebrew and English, and the transcript sits inside the message. Your agent can search what people typed and what they *said*.
- **Files arrive ready to open.** Photos, PDFs, documents and videos are kept and announced with name, type and size. The agent fetches one with a single call when it needs it. Older files are pulled from your phone on request.
- **Senders by name.** Senders come back by the name you saved; group member lists never include numbers. Someone you never saved may appear by number.
- **Cheap questions stay cheap.** `activity` says which chats moved and how much, with no text, so "what did I miss?" costs a fraction of reading everything.
- **Refusals that help.** Ask for a chat that is not open and the answer names what *is* open. "No messages" and "you cannot see that chat" are never confused.
- **Full history.** Everything WhatsApp syncs to a linked device, often years of it, plus everything new, searchable across every chat you opened. Agents on Free look back a month and on Starter 3 months; all of it is on Pro.

This is what an agent gets back when it catches up on a parents group (shortened):

```
{
  "chat": "Oak Street parents",
  "messages": [
    {
      "from": "Dana",
      "at_iso": "2026-10-26T06:12:00.000Z",
      "body": "",
      "media": {
        "kind": "voice",
        "duration_seconds": 41,
        "transcript_state": "done",
        "transcript": "Quick update: the trip moved to Thursday, buses leave at 8:15, bring a hat and a packed lunch."
      }
    },
    {
      "from": "Yossi",
      "at_iso": "2026-10-26T07:03:00.000Z",
      "body": "Permission slip attached, please sign by Wednesday",
      "media": {
        "kind": "document",
        "filename": "trip-permission.pdf",
        "state": "available",
        "fetch_with": "get_media",
        "ref": "r1_..."
      }
    }
  ]
}
```

## The nine tools

Tools appear only when the agent may use them: an agent without send permission never even sees `send`.

| Tool | What it does | Good for |
| --- | --- | --- |
| `allowed_chats` | The chats open to agents and what may be done in each | Knowing the whole world before it starts |
| `activity` | Which chats moved since a time, with counts and no text | "What did I miss?" for almost nothing |
| `catch_up` | Messages since a time, in one chat or all of them, names resolved, voice notes as text | Summaries, digests, follow-ups |
| `search` | Text search in one chat or all, including what was said in voice notes | "Did anyone mention the plumber?" |
| `people` | Who you talk with across open chats, and where | Context about the people in your life |
| `group_members` | Members of one open group, by name, admins marked | "Who is in the building committee?" |
| `documents` | Every PDF, Word file and sheet sent in open chats | "Find the contract Avi sent in June" |
| `get_media` | One photo, document, video or audio file | Reading the file itself |
| `send` | A message or file, only where you allowed sending, within the daily cap | Replies you asked for |

## Hosted or self-hosted WhatsApp MCP?

Open-source WhatsApp MCP servers are a fine choice if you want to run one. Here is the honest difference.

|  | Self-hosted (open source) | Circles |
| --- | --- | --- |
| Setup | Clone a repo, run a bridge and an MCP server, scan a QR code from your computer | Link from your phone, connect your agent with a tap, an address or a token |
| Runs when your laptop sleeps | No, unless you run a server | Yes, hosted |
| Works with Claude on the web and phone | Needs a public URL and auth you build | Yes, remote MCP with OAuth |
| Voice notes | Audio files; transcription is yours to add | Transcribed automatically, Hebrew and English |
| Which chats the agent sees | Usually everything | Only the chats you open, set per chat for all your agents |
| Sending | Usually unrestricted | Off by default, per chat, capped per day, logged |
| Cost | Free, plus your time and a server | Free for 2 chats; Pro $29 a month |

More detail, and when self-hosting is the better call: [Circles vs self-hosted WhatsApp MCP servers](https://usecircles.app/en/compare/self-hosted-whatsapp-mcp).

## You decide what your agents see

Every chat has one of three levels. **Hidden**: it does not exist for agents, not in lists, not in search, not even named in a refusal. **Read**: agents can read and search it, and there is no way to send. **Read and send**: an agent may also write there, as you, within a daily cap you set.

Every request an agent makes, including the ones Circles refused, is in your activity log. Disconnect an agent and its access ends at once. [How Circles keeps your chats in your hands](https://usecircles.app/en/security).

## Questions and answers

### Is there a WhatsApp MCP server for Claude?

Yes. Circles is a hosted WhatsApp MCP server that Claude connects to as a custom connector, with one address and an approval. It works with your personal number and only the chats you choose.

### Is there a remote WhatsApp MCP server URL?

Yes: `https://app.usecircles.app/api/mcp`. It is a remote MCP server over HTTP with OAuth 2.1, so clients that support custom connectors can add it by address. You need a Circles account with your number linked.

### Do I need WhatsApp Business or a second number?

No. Circles links your existing personal WhatsApp as a linked device, the same way WhatsApp Web does. You keep using WhatsApp on your phone as usual.

### Does it transcribe voice notes?

Yes. Voice notes and audio files are transcribed automatically, in Hebrew and English, and the text arrives inside the message for your agent to read and search.

### Can the agent send messages as me?

Only in chats you opened for sending, and only up to a daily cap you set (default 5 across all agents). Sending is off until you turn it on, and a send is never retried automatically.

### Can WhatsApp disconnect or ban my number?

Any unofficial client, such as a linked device not made by WhatsApp, is outside its terms, and no one can promise a linked device will never be logged out. Circles reads by default, caps sends, never broadcasts, and connects each customer through a dedicated IP address shared with no one else.

### How much does a WhatsApp MCP cost?

Circles has plans from $0: Free for 2 chats, Starter at $9.90 a month for up to 5, and Pro at $29 a month (₪99 in Israel) for every chat and sending, with 14 days of Pro free. Your agent's own subscription is separate.

## Keep reading

- [Every agent, step by step](https://usecircles.app/en/agents): Instinct, Claude, ChatGPT, Codex, Claude Code, Cursor, Grok and the API.
- [What people ask their agents](https://usecircles.app/en/use-cases): Group catch-ups, voice notes, finding files, daily digests, replies.
- [Compare](https://usecircles.app/en/compare): Self-hosted servers, the Business API, Meta AI, exporting chats.

---

14 days free. Link your number, pick the chats, then connect Instinct with one tap or Claude, ChatGPT and Codex with one address. Start: https://usecircles.app/start?lang=en