Partner werden|Affiliate werden
First time hearing about MCP?Jump there ↓

Drive your WhatsApp inbox
from your AI assistant.

Connect TimelinesAI to Claude Code, Cursor, or Codex with one config line. Your AI can now list chats, summarise threads, label, assign, react, and reply — the same as you would in the web UI, just by asking in plain English. OAuth sign-in, no API tokens to manage, eighteen tools across discovery, messaging, and triage.

See it in action ↓Install kit ↓
See it in action

One prompt, real actions across your inbox

Here's a real Monday-morning triage prompt. The assistant runs across every WhatsApp number in your TimelinesAI workspace, surfaces what needs attention, and takes the actions you'd normally take by hand — labels, reassignments, internal notes — in one turn.

✦Claude Code·claude.ai/code

You

You

Walk my Monday inbox. Group unread chats by responsible rep, surface anything that's been sitting more than two business days, label those 'follow-up-needed', and assign Friday's overnight chats to whoever is online today.

✦

AI assistant

Across 6 connected WhatsApp accounts, 47 unread chats: • Maria — 18 unread (oldest: 3d 4h — "any update on the quote?") • Diego — 14 unread (oldest: 2d 6h) • Sasha — 9 unread (oldest: 1d 2h) • Unassigned — 6 chats (all from Friday after 7pm) Action taken: ✓ Labeled 23 chats older than 2 business days with 'follow-up-needed' ✓ Reassigned the 6 Friday-overnight chats to Diego (online now) ✓ Left a private note on each summarising the customer's last ask Want me to draft replies for the 5 oldest in the follow-up-needed queue?

Other prompts that work the same way:

>Reopen chat 87412, label it ‘escalated’, and assign to jane@company.com.>Find every chat where a customer wrote ‘invoice’ this week and react ❤️ to the most recent message.>Draft a check-in for the top 3 stalled deals from Friday — show me before sending.>Close every chat labeled ‘spam’ that hasn't had activity in 30 days.>Summarise what happened in the support inbox today, grouped by rep.

Each of those is a real prompt you can paste straight into Claude Code, Cursor, or Codex after the install kit below. No API calls to write, no templates to fill in. The assistant calls the eighteen MCP tools on your behalf and confirms what it did.

What is this?

What is the WhatsApp MCP?

The Model Context Protocol (MCP) is the standard way to give an AI assistant a set of tools it can call on your behalf. The TimelinesAI WhatsApp MCP exposes eighteen of these tools — list chats, send messages, label, assign, react, check quotas, and more — so Claude Code, Cursor, or Codex can drive your real WhatsApp inbox the same way a teammate would. Connect once via OAuth and the assistant takes it from there.

Three clients, all on the same paid tier you're already on. The MCP itself is free and ships with TimelinesAI on every plan that includes the Public API. You only pay for the AI assistant you already use — Claude Pro/Max, Cursor Pro, or ChatGPT Pro. For daily team triage on large inboxes, the $20 tiers run out fast — budget the $100–$200 plan if your team relies on it.

Pick your AI client

Recommended

Claude Code

Anthropic's coding agent. Best tool-calling depth and the deepest context window — the only client that handles long inbox runs reliably. Web at claude.ai/code or the desktop app. Included with Claude Pro $20/mo for light use, Max $100–$200/mo for daily team triage.

claude.ai/code →

Cursor

The AI code editor. Native MCP support. Works well for ad-hoc inbox questions next to your code or notes. Pro plan $20/mo or pay-per-token.

cursor.com →

Codex

OpenAI's terminal agent — the GPT-5 equivalent of Claude Code. Same MCP protocol, same TimelinesAI tools. Useful if your team is already on a ChatGPT Pro plan.

developers.openai.com/codex →
Install kit

Two steps. Under five minutes. No SDK.

Everything you need to start is one config block and an OAuth sign-in. Pick the snippet for your client, paste it, restart, and the first time the assistant touches WhatsApp a browser tab opens for the TimelinesAI login. That's the whole setup.

  1. 1

    Add the MCP config to your AI client

    Pick the block below for your client and paste it into the right place. Claude Code does it in one shell command. Cursor and Codex want you to edit a config file directly. All three end up pointed at the same endpoint: mcp.services.timelines.ai/mcp.

    Open the full install snippets →Or browse the repo first →
    # Claude Code — one command, no config file:
claude mcp add timelinesai -- \
  npx -y mcp-remote@latest \
  https://mcp.services.timelines.ai/mcp \
  --host 127.0.0.1

# Cursor — add to ~/.cursor/mcp.json:
{
  "mcpServers": {
    "timelinesai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.services.timelines.ai/mcp",
        "--host", "127.0.0.1"
      ]
    }
  }
}

# Codex — add to ~/.codex/config.toml:
[mcp_servers.timelinesai]
command = "npx"
args = ["-y", "mcp-remote@latest", "https://mcp.services.timelines.ai/mcp", "--host", "127.0.0.1"]
  2. 2

    Restart your client and sign in

    Fully quit and reopen your client (for Claude Desktop, Cmd-Q / Alt-F4, not just close the window). The first time you ask anything about WhatsApp, a browser tab opens on mcp.services.timelines.ai — log in with your TimelinesAI account and grant access. The OAuth token is cached locally; subsequent sessions reconnect silently.

    Don't have a TimelinesAI account yet? Sign up →Already a customer? Sign in to your workspace →
✓

Done. Your assistant can now see your chats, send messages, label, assign, and react. The rest of this page covers safety (writes are real, quota is shared) and the developer handoff. As a user, you can stop reading here and start asking.

First 15 minutes

What to ask in your first 15 minutes

After install, don't open with a bulk send. Walk through these five prompts in order — they progress from read-only to a guarded write to the draft-first pattern. By minute 15 the assistant has earned your trust enough to draft real customer replies (and only draft; you still approve before send).

  1. 10:00–2:00
    What's the state of my TimelinesAI workspace — accounts, quota, team?

    Confirms the MCP is connected, surfaces basic context, no writes.

  2. 22:00–5:00
    List the 10 most recent open chats. Don't open any.

    Real data in front of you. Still read-only.

  3. 35:00–9:00
    Summarize the conversation in chat <ID> in 3 bullets.

    First call to chat_history / get_chat_messages. AI is reading, summarizing.

  4. 49:00–12:00
    Add label 'reviewed' to chat <ID>.

    First write. Idempotent, reversible, visible in the UI. No messaging credit cost.

  5. 512:00–15:00
    Draft a reply to chat <ID> based on the conversation, but show me the draft before sending. Don't send yet.

    The draft-first pattern. AI composes the message in chat; you approve; THEN it sends. This is the shape every customer-facing prompt should follow.

Tool atlas

All 18 tools, grouped by what they unlock

The MCP server exposes 18 tools across four groups. The naming uses TimelinesAI's protocol convention; the descriptions below are the human translation. Two of the 18 (`message_react`, `chat_history`) are MCP-only — they don't have a public REST endpoint, only the MCP server can call them.

Situational awareness3

Read-only introspection. Low quota cost. Safe at any time.

  • workspace_quotas

    Plan, seats, messaging + API quotas, billing period

    Example prompt: How much messaging quota have I burned this month?

  • workspace_whatsapp_accounts

    Every connected WhatsApp number, status, owner

    Example prompt: Which of my WA accounts is disconnected right now?

  • workspace_team

    Teammates, roles, emails (for chat_assign)

    Example prompt: Find Diego's email so I can assign chats to him.

Find what matters5

Browse and read. No writes. No messaging-credit cost.

  • list_chats

    Filter chats by status, labels, assignee, dates — paginated 50/page

    Example prompt: List unread chats assigned to me, opened this week.

  • chat_details

    Full metadata for one chat

    Example prompt: Pull details on chat 99653.

  • chat_historyMCP-only

    Context window around a specific message

    Example prompt: Show me the conversation around message UID abc-123.

  • get_chat_messages

    Page through messages in one chat

    Example prompt: Get the last 20 messages from chat 99653.

  • message_details

    Inspect a single message by UID

    Example prompt: Show me message UID abc-123 in full.

Act on it4

Quota-consuming. Each outbound message draws from the same monthly budget as the UI.

  • chat_send_message

    Send into an existing chat (text, attachment, or threaded reply)

    Example prompt: Reply to chat 99653 with 'On my way, ETA 10 min.'

  • whatsapp_account_send_message

    Cold-send to any phone via a specific WA account

    Example prompt: Send 'Hello from MCP' to +15551234567 from my UK account.

  • message_reply

    Threaded reply to a specific message UID

    Example prompt: Reply to message UID abc-123 with 'Got it, will follow up.'

  • message_reactMCP-only

    Set or clear an emoji reaction on a message

    Example prompt: React 👍 to the last message in chat 99653.

Organize the team6

State + triage. Idempotent. No messaging-credit cost. All hit the same PATCH /chats/{id} endpoint underneath.

  • chat_open

    Reopen a closed chat

    Example prompt: Reopen chat 87412.

  • chat_close

    Close (archive from active inbox)

    Example prompt: Close chat 99653 — handled.

  • chat_set_label

    Add a label (REPLACE semantics — wrapper handles union)

    Example prompt: Label chat 99653 as 'sales-qualified'.

  • chat_remove_label

    Remove a label

    Example prompt: Remove 'spam' from chat 99653.

  • chat_assign

    Assign to a teammate by email

    Example prompt: Assign chat 99653 to jane@company.com.

  • chat_unassign

    Clear the current assignee

    Example prompt: Unassign chat 99653 — needs re-routing.

Setup walkthrough

Connect TimelinesAI, step by step

If you already have a TimelinesAI workspace with a WhatsApp number connected, step 1 of the install kit is all you need. If you don't yet — here's the full walkthrough. Four steps, all you need to find your way around app.timelines.ai the first time.

  1. 1

    Create your TimelinesAI workspace

    Sign up with a work email. A workspace is created for you automatically — one workspace per organisation, with multiple WhatsApp numbers living inside it. You don't need a credit card; the free trial covers enough message credits to finish this guide.

    Open the sign-up page →
  2. 2

    Add your WhatsApp number

    Once signed in, go to the WhatsApp Accounts page and click “Add a WhatsApp account”. A QR code appears. On the phone that holds your business number, open WhatsApp → Settings → Linked devices → Link a device, and scan the QR. Same flow as WhatsApp Web — TimelinesAI is the managed layer on top that handles session recovery, multi-device, shared inbox, and the API your AI assistant is about to use.

    Open WhatsApp Accounts →
  3. 3

    Confirm the number is connected

    Back on the WhatsApp Accounts page, your number should show status “connected” within a few seconds of the scan. Without a connected WhatsApp account the MCP tools will return empty results or errors — it's a remote control for a real inbox, not a sandbox. If the number stays in “connecting” for more than 30 seconds, see the snags list below.

    Check WhatsApp Accounts →
  4. 4

    Sign in to the MCP via OAuth

    Open your AI client (Claude Code, Cursor, or Codex). The first time you ask the assistant anything about your WhatsApp, the mcp-remote proxy opens a browser tab at mcp.services.timelines.ai. Log in with the same TimelinesAI account from step 1 and grant access. That's it — no API token to copy, no env var to set. The OAuth token is cached locally and reused across sessions.

    Open the dashboard →

Common snags

  • Browser tab didn't open on first connect. mcp-remote prints an OAuth URL into the client's log when it can't auto-launch a browser (common on remote SSH sessions). Copy the URL from the log, open it in any browser, authorise, and the client picks it up automatically.
  • Cursor reports a redirect-URI mismatch. You're on an older mcp-remote build. Make sure the config uses mcp-remote@latest (with the @latest tag) so npx fetches a build that supports Cursor's dynamic localhost callback.
  • Tools return “no connected WhatsApp accounts.” The MCP is a remote control for your real TimelinesAI inbox — it doesn't simulate one. Finish step 2 above (scan the QR) before retrying, then ask the assistant to run workspace_whatsapp_accounts to confirm it can see the number.
  • Claude Desktop reads stale config after a restart. Close-the-window doesn't reload MCP servers — you have to fully quit (Cmd-Q on macOS, right-click tray icon → Quit on Windows) and reopen. Same goes for Cursor when you change ~/.cursor/mcp.json.
Watch out

When to be careful

Five things to know before you let your assistant touch a live customer inbox. The technical gotchas — OAuth refresh, pagination, label-replace semantics — are handled by the MCP server itself, so you never have to think about them. These five are strategic, not technical, and three of them are real API behaviors we caught by probing every failure mode on purpose.

!
Writes are real and indistinguishable from the UI. When the assistant sends a message via chat_send_message or whatsapp_account_send_message, the recipient cannot tell whether you typed it yourself or whether an AI did. There is no sandbox, no dry-run flag, no undo. Build the draft-first pattern (see below) into every customer-facing prompt.
!
MCP quota is the same quota the web UI uses. Every message the assistant sends draws from your workspace's monthly messaging budget — the same one your team uses from the dashboard. Ask the assistant to call workspace_quotas before bulk sends to see headroom, and confirm the count before it fires.
!
Realistic daily use needs a paid Claude Max or ChatGPT Pro plan. The $20 tiers (Claude Pro, ChatGPT Plus) burn out fast on inbox-sized data — see the Cost realism section below for the measured numbers. For a team that runs this every morning, the $100–$200 plans are the realistic floor. Claude Desktop chat mode is supported in the README but times out on long runs — use Claude Code, Cursor, or Codex instead.

Findings from probing every failure mode

Five real behaviors we caught by deliberately triggering every failure mode against a real workspace. Two of them are silent acceptance bugs you should know about:

  • `chat_assign` silently accepts bogus emails. Always verify the teammate exists first. We probed `chat_assign(chat_id, responsible_email='ghost@nowhere.invalid')` and the API returned 200 OK — no validation that the email maps to a real teammate. The chat ends up unreachable. The MCP tool description tells the AI to call `workspace_team` first; if you write your own integration, mirror that check.

  • Labels accept any length. The UI truncates; the underlying data persists in full. A 256-character label string was accepted with 200 OK. The TimelinesAI UI shows a truncated version, but the data round-trips intact through the API. Keep labels under 30 characters in practice — the schema doesn't enforce it.

  • Two MCP tools have no public-REST equivalent. `message_react` and `chat_history` are MCP-only — the underlying REST endpoint is internal. You can read reactions with `GET /messages/{uid}/reactions` but you can't set or clear them via the public API. The MCP server is the supported path; rolling your own integration won't replicate them.

  • Writes are real and indistinguishable from the UI. `chat_send_message`, `whatsapp_account_send_message`, and `message_reply` all draw from the same monthly messaging budget as your team's manual sends, and the recipient cannot tell the difference. No sandbox, no dry-run flag. Build the draft-first pattern into your prompts (see below).

  • Quota is shared with the UI. Every message the AI sends counts against your workspace's monthly messaging quota — exactly the same one your team uses from the dashboard. Ask the AI to call `workspace_quotas` before any bulk-send to see headroom, and confirm the count before it fires.

The draft-first pattern

When a prompt could lead to a customer-facing send, phrase it so the AI has to surface a draft before sending. The shape that works: "Find chats matching X. For each, **draft** a reply. **Show me the drafts before sending.** Once I confirm, then call chat_send_message." The assistant ends up calling list_chats + get_chat_messages + composing the message text in chat — but NOT calling chat_send_message until you reply with "send 1, 3, 5" (or whatever subset). This is the single most important pattern for trusting AI with a shared inbox.

Cost realism

What a real triage actually costs

We instrumented one Monday-style read-only triage end-to-end against a real Support workspace — 10 pages of `list_chats(read=false)` plus 20 deep `get_chat_messages` calls plus a `workspace_team` lookup. Here's what it spent:

Measured · 10 pages list_chats + 20 deep get_chat_messages + 1 workspace_team
  • API calls31

    10 pages of list_chats + 20 deep get_chat_messages + 1 workspace_team

  • Messaging credits0

    Read-only triage. Sends add credits 1:1.

  • Wall clock~28s

    Includes 0.5s politeness sleeps to stay under TimelinesAI's ~2 rps soft limit

  • Response payload~421 KB

    Total JSON returned across all calls

  • Token estimate (response data only)~105 K tokens

    Add the user prompt, system prompt, tool definitions, and the AI's own reasoning — full session typically 1.5–3× this

Token counts shown are response payloads only. A full Claude Code session also pays for the user prompt, system prompt, tool definitions, and the AI's own reasoning — total session tokens typically 1.5–3× the response figure. At Claude Pro ($20/mo) you'll exhaust the daily allowance in 1–2 runs; at Claude Max ($100/mo) you can run this 5–10× daily and stay in headroom.

Go technical

For developers: where the rest lives

This page is the user guide and the install kit. Everything deeper — the full eighteen-tool reference, the streamable-HTTP endpoint details, the OAuth + PKCE flow, the Claude Desktop config, the lighter read-only alternative — lives in the three resources below. If you're shipping this to a team, send these links to whoever is going to wire it up.

{ }

MCP server repo + 18-tool catalog →

The full MCP server source, the docs/tools.md reference with arguments and example prompts for all 18 tools, ready-to-copy config snippets for Claude Code, Cursor, Codex, and Claude Desktop, and the streamable-HTTP endpoint at mcp.services.timelines.ai. MIT licensed. This is the first link to send any developer on your team.

github.com/InitechSoftware/whatsapp-mcp-by-timelinesai

API

TimelinesAI Public API reference →

The official docs for every endpoint the MCP tools sit on top of: whatsapp_accounts, chats, messages, labels, notes, files, webhooks, quotas. Request/response schemas and auth. If you want to build a custom integration that the 18-tool MCP doesn't cover, start here — it's the same REST API.

timelinesai.mintlify.app/public-api-reference

→

Read-only analytics? See the Claude Code skills guide →

This MCP is built for action — label, assign, reply, react, reopen. If all you want is to ask analytical questions over your inbox without writes (“what were our top topics this month?”, “which five customers haven't been replied to?”), the Claude Code skills guide is the lighter-weight path. Same TimelinesAI API, different shape, no OAuth.

timelines.ai/guide/claude-code-whatsapp-analytics

If something's missing from the MCP or the docs, open an issue on the server repo. It's MIT-licensed, the eighteen tools are versioned, and the team ships fixes weekly.

Start triaging

Get the MCP server on GitHub →

Full source, 18-tool catalog, OAuth flow, config snippets for Claude Code, Cursor, Codex, and Claude Desktop. MIT licensed, listed in the Anthropic MCP Registry, Smithery, and Glama. Maintained by TimelinesAI.

Capability guide · 2026 · Canonical URL timelines.ai/whatsapp-mcp-guide