# Cursor with your WhatsApp: one block in mcp.json

> Circles lets Cursor's agent read the WhatsApp chats you choose, over MCP. Make a token in Circles, paste one block into Cursor's mcp.json, and the client's messages are in reach while you code.

**To connect Cursor to WhatsApp:** link your number in Circles, make a token under *New token*, and paste the config Circles writes into `~/.cursor/mcp.json`. Cursor's agent can then read and search the chats you opened, for Circles free for 2 chats, or $29 a month on Pro (₪99 in Israel) with 14 days free, as of October 2026.

Source: https://usecircles.app/en/agents/cursor · Updated 2026-10-27

## Three steps, one paste

1. **Link your WhatsApp in Circles**: Start your trial, then link your number as a linked device: a code typed on your phone, or a QR on your computer. Same number, same WhatsApp on your phone. History arrives in about 5 to 15 minutes, and you can connect your agent meanwhile.
2. **Make a token**: On Circles' Agents page, choose *New token*, pick Cursor, keep MCP, and choose what it allows. Then *Copy config*: the block below, with your token inside.
3. **Paste it into Cursor's mcp.json**: `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` in one project. Cursor's MCP settings show `circles` and its tools.

## The config

This is what *Copy config* gives you, with the token masked here. If your `mcp.json` already lists servers, add `circles` beside them.

```
{
  "mcpServers": {
    "circles": {
      "url": "https://app.usecircles.app/api/mcp",
      "headers": { "Authorization": "Bearer circ_..." }
    }
  }
}
```

## Why a token, and keeping it safe

Keep the token out of a project file you commit. If one leaks, disconnect it in Circles; it stops working at once.

Why a token? Cursor finishes its sign-in on an address of its own kind (a custom scheme), and Circles accepts only web and local addresses for that. So Cursor uses a token, and there is no "Add to Cursor" button.

## What to ask Cursor

For developers. Invented examples, real shapes.

- **"Read the crash report in the client group and find where it comes from"**: Cursor's agent reads the group, voice notes as text, and goes to the code with what the client actually said.
- **"Summarize what the beta testers group said about the new editor this week"**: `catch_up` on one group since a date, senders by the name you saved.
- **"Get the screenshot Dana sent and fix the layout it shows"**: The agent fetches the image and looks at it itself. Circles does not describe images.
- **"Write the update for the users group from today's changes"**: It drafts; it posts only if you opened that group for sending.

## What Cursor can and cannot do here

**Cursor can:**

- See which chats you opened, and which of them moved since a time, with counts and no text (`allowed_chats`, `activity`).
- Catch up and search, in one chat or all of them, with senders by name and voice notes already transcribed (`catch_up`, `search`).
- See who you talk with and who is in a group, by the name you saved; group member lists never include numbers (`people`, `group_members`).
- List the documents sent in your chats and open a photo, PDF or file, up to 50 MB (`documents`, `get_media`). Cursor opens the file and reads it itself.
- Send a message or a file, only in chats you opened for sending and within your daily cap (`send`).

**Cursor cannot:**

- See a hidden chat. It is not listed, not searchable, and never named, not even in a refusal.
- Send in a chat you opened for reading only, go past the daily cap (default 5 across all your agents), or have a send retried automatically.
- Reply with a quote or react with an emoji. Those exist only in the [HTTP API](https://usecircles.app/en/whatsapp-api-personal-number).
- Keep access after you disconnect it. Disconnecting ends it at once, and every request it made stays in your activity log.

## Questions and answers

### Can Cursor read WhatsApp messages?

Yes, through Circles, a hosted WhatsApp MCP server. Paste the config with a token into Cursor's `mcp.json`, and Cursor's agent reads the chats you opened.

### Why does Cursor need a token?

Cursor's sign-in returns to a custom app address, which Circles does not accept. A token in the config is the way Cursor connects.

### Is there an Add to Cursor button?

No. You paste one block, which Circles writes for you with the token inside.

### Where does the config go?

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` inside one project. Keep the token out of anything you commit.

### Can Cursor send WhatsApp messages?

Only if the token allows sending, and only in chats you opened for sending, within your daily cap. A send is never retried automatically.

## Keep reading

- [Claude Code](https://usecircles.app/en/agents/claude-code): One command and a token.
- [Codex](https://usecircles.app/en/agents/codex): One address, no token.
- [What the agent can reach](https://usecircles.app/en/security): Per-chat permissions and the activity log.

---

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