--- title: "Connect WhatsApp to Cursor via MCP — WhatsMCP Blog" description: "Connect WhatsApp to Cursor's agent with WhatsMCP: add one entry to mcp.json, sign in with OAuth or an env-var API key, and build against a real number." url: "https://whatsmcp.com/blog/connect-whatsmcp-to-cursor" --- Cursor's agent already reads your code, runs your tests and edits your files. Add WhatsMCP and it can reach WhatsApp too: check what a test message actually looked like on the phone, send yourself a build notification, prototype a support bot against a real number, or read customer feedback while you fix the bug it describes — without leaving the editor. This guide shows how to connect WhatsApp to **Cursor** through MCP: the `mcp.json` setup with OAuth or an API key, where the file lives, what the agent can do once connected, developer-focused prompts, troubleshooting and FAQs. ![Diagram: the Cursor agent connects over MCP to api.whatsmcp.com/mcp, which reaches your WhatsApp number as a linked device](https://content.whatsmcp.com/uploads/whatsapp_cursor_mcp_architecture_fc1dcab609.webp) ## Why connect Cursor to WhatsApp - **Build WhatsApp features faster.** Prototype a bot or a notification flow against a real number, and look at exactly what was sent and received. - **Debug with real data.** Ask the agent to fetch the message a user complained about, then fix the code that produced it. - **Notify yourself.** "Message me on WhatsApp when the migration finishes" is one prompt. - **One integration, two interfaces.** What the agent does over MCP, your production code can do over the REST API or webhooks. ## Before you start - **A WhatsMCP workspace.** [Sign up free](https://console.whatsmcp.com/register?utm_source=blog&utm_medium=article&utm_campaign=connect-whatsmcp-to-cursor&utm_content=before-you-start). - **A linked number.** - *Personal number:* at **Add a number** (setup opens it; later it's **Fleet → Add Number**) choose **Personal WhatsApp → Link a device via QR** and scan the code from **WhatsApp → Settings → Linked devices → Link a device**. The first Personal number in a workspace takes the free line automatically; any other stays suspended until you choose a plan. New Personal numbers run through WhatsMCP's Default Random VPN unless you set your own WireGuard or SOCKS5 egress. - *Official Business number:* choose **WhatsApp Business → Connect with Facebook**, then a Business plan — the number stays suspended until it has one, and your workspace's first Business plan starts with a 7-day free trial. See [Connect WhatsApp Business API to Claude](/blog/connect-whatsapp-business-api-to-claude). - **The endpoint:** `https://api.whatsmcp.com/mcp` (Streamable HTTP). ![The WhatsMCP console Pair device page: a QR code above a progress indicator reading code, scanned, syncing, ready](https://content.whatsmcp.com/uploads/console_pair_device_fecfe5a9da.webp) ## How to connect Cursor to WhatsMCP Cursor reads MCP servers from an `mcp.json` file: - **Global** — `~/.cursor/mcp.json`, available in every project. - **Project** — `.cursor/mcp.json` in the repository, for one project (and shareable with your team, minus any secrets). ![Two Cursor mcp.json examples for WhatsMCP: a URL-only entry that signs in with OAuth, and one that sends an API key from an environment variable](https://content.whatsmcp.com/uploads/connect_cursor_to_whatsmcp_mcp_json_596d906245.webp) ### With OAuth (recommended) Add the server with just its URL: ```json { "mcpServers": { "whatsmcp": { "url": "https://api.whatsmcp.com/mcp" } } } ``` With no headers, Cursor runs the standard MCP OAuth flow: it discovers WhatsMCP's sign-in, registers itself, and opens your browser so you can approve the connection in the WhatsMCP console. Nothing secret is written to disk, and you can revoke Cursor on its own at **Console → Connections**. ### With an API key For a shared project, a remote dev box, or anywhere a browser sign-in is awkward, use a key from **Console → API keys** and keep it in the environment: ```json { "mcpServers": { "whatsmcp": { "url": "https://api.whatsmcp.com/mcp", "headers": { "Authorization": "Bearer ${env:WHATSMCP_API_KEY}" } } } } ``` ```sh export WHATSMCP_API_KEY=wamcp_live_… ``` Cursor substitutes `${env:NAME}` inside `url` and `headers`, so the key never lands in the file — safe to commit the project config. `x-api-key: ${env:WHATSMCP_API_KEY}` works too. Keys are shown once; mint one per machine or teammate so you can revoke individually. ### Check that it's connected Open Cursor's settings and find the MCP section, where `whatsmcp` should show as enabled with its tools listed. Then ask the agent: *"Using WhatsMCP, list my WhatsApp accounts."* It should call `wa_list_accounts` and show your numbers. ## What happens under the hood The OAuth flow is standard OAuth 2.1: Cursor reads WhatsMCP's published metadata, registers as a client, and completes an authorization-code exchange with PKCE. The resulting token is bound to WhatsMCP and its refresh token rotates on every use. ![The five steps of WhatsMCP's OAuth sign-in: add the URL, discover metadata, register the client, approve in the console, receive a scoped token](https://content.whatsmcp.com/uploads/whatsmcp_oauth_sign_in_flow_689ce49906.webp) Every tool call is scoped to your workspace, and your plan decides which tools the agent sees — up to **42** on a Personal number and **15** on a Business number, out of 45 in all. ![The 45 WhatsMCP tools grouped by category: accounts and plan, messaging, message operations, contacts, groups and channels, group admin, blocklist, calls and AI voice, webhooks](https://content.whatsmcp.com/uploads/whatsmcp_45_whatsapp_tools_1b6d4ee6a5.webp) ## Prompts for developers **1. See what users see.** > "Fetch the last five messages my test number received from +44 7700 900111 and show the raw JSON." `wa_list_messages` and `wa_get_message` return the stored records — handy when you're writing a parser. ![A Cursor agent session showing one prompt turning into wa_list_accounts, wa_list_messages and wa_get_chat calls](https://content.whatsmcp.com/uploads/cursor_whatsapp_inbox_triage_tool_calls_ad618265ae.webp) **2. Notify me when it's done.** > "Run the migration, and when it finishes send me a WhatsApp message with the result and how long it took." The agent runs the command, then calls `wa_send_message` to your own number. **3. Prototype a webhook receiver.** > "Scaffold an Express endpoint that verifies WhatsMCP's webhook signature, then register it with wa_set_webhook pointing at my ngrok URL." `wa_set_webhook` returns the signing secret once; the agent can wire it into your `.env`. The payload format is in [WhatsMCP webhooks: setup guide](/blog/whatsmcp-webhooks-setup). **4. Turn feedback into a fix.** > "Read today's messages in the 'Beta testers' group, list the bugs people reported, and open the files that are most likely responsible." `wa_list_groups` and `wa_get_chat` read the group; the agent does the rest in your codebase. **5. Test a template** (Business numbers). > "Create a utility template order_shipped with name and tracking-number variables, then send it to my test number once it's approved." `wa_create_template`, `wa_list_templates`, then `wa_send_message`. ## Troubleshooting - **The browser doesn't open for sign-in.** Toggle the server off and on in Cursor's MCP settings, or restart Cursor. If you're on a remote machine, use the API-key config instead. - **401 with an API key.** Check the variable is exported in the environment Cursor was started from; `${env:…}` resolves when Cursor launches. - **A tool is missing.** It's not in your plan, or it's Personal-only on a Business number. `wa_get_plan` and **Console → Help** show what's included. - **Too many tools for the agent.** Keep WhatsMCP enabled only in projects that need it, by putting it in the project `.cursor/mcp.json` rather than the global file. ## Good habits - **Use a test number** while developing, and keep production numbers for production keys. - **Secrets in the environment, never in `mcp.json`.** - **Personal numbers** connect as linked devices, which falls outside WhatsApp's terms of service; for customer messaging, use an official Business number. - **Review access** at **Console → Connections** and **Console → API keys**. ## FAQ ### Does Cursor support remote MCP servers with OAuth? Yes. A `url` entry with no `headers` makes Cursor run the MCP OAuth sign-in in your browser. ### Should I use the global or project config? Global for personal use across projects; project (`.cursor/mcp.json`) when a repository needs WhatsApp tools, with the key read from an environment variable. ### Can my production app use the same number? Yes. Use the REST API or webhooks with their own API key; Cursor's connection is independent and revocable on its own. ### Does this work with other editors and agents? Yes — any client that speaks Streamable HTTP MCP. See the guides for [Claude](/blog/connect-whatsmcp-to-claude), [ChatGPT](/blog/connect-whatsmcp-to-chatgpt) and [Grok](/blog/connect-whatsmcp-to-grok). ## Get started [Create your free WhatsMCP workspace](https://console.whatsmcp.com/register?utm_source=blog&utm_medium=article&utm_campaign=connect-whatsmcp-to-cursor&utm_content=get-started), link a test number, and add three lines to `mcp.json`. The complete tool reference is at [whatsmcp.com/docs/mcp](/docs/mcp).