---
name: timelinesai-whatsapp-mcp-setup
description: Connect the TimelinesAI WhatsApp MCP server to this AI agent, for new and existing TimelinesAI users, and verify it works.
---

# Set up TimelinesAI WhatsApp MCP

You are connecting the TimelinesAI WhatsApp MCP server for the user. Follow this file step by step. It works for people who already use TimelinesAI and for people who are new.

## How to run

- Do the work yourself when you have terminal or file access. Do not just hand the user commands to copy.
- Do not ask the user whether they have an account or a connected number. Connect first, then read the result of the check in step 4 and branch on it.
- Pause only for things you cannot do: sign-in or signup in the browser, scanning the WhatsApp QR code, and reloading the client.
- Before editing any config file, read it and merge the new entry. Never overwrite other servers.
- Never send a WhatsApp message during setup. Use read-only tools only.
- Report only what you verified. If a step is blocked, say why and continue with the rest.
- Talk to the user in the language they write in. Keep commands, tool names and URLs exactly as written.

Connector URL: `https://mcp.services.timelines.ai/mcp`
Auth: OAuth in the browser. No API key.

## 1. Check whether it is already connected

If a server named `timelinesai` is already configured in this client, skip to step 4. If it is configured but its tools are missing and it is not waiting on sign-in, go to step 3.

## 2. Add the server

Pick the route for the client you are running in. All routes use the same remote (Streamable HTTP) URL, no proxy needed.

### Claude Code
```
claude mcp add --scope user --transport http timelinesai https://mcp.services.timelines.ai/mcp
```
Sign-in opens in the browser on the first tool call.

### Cursor
Merge into `~/.cursor/mcp.json` under `mcpServers`:
```json
"timelinesai": { "url": "https://mcp.services.timelines.ai/mcp" }
```
Sign-in opens on the first tool call.

### Codex
Append to `~/.codex/config.toml`:
```toml
[mcp_servers.timelinesai]
url = "https://mcp.services.timelines.ai/mcp"
```
Then run `codex mcp login timelinesai` once. The user approves in the browser. Codex does not start sign-in on its own.

### Grok Build
```
grok mcp add timelinesai https://mcp.services.timelines.ai/mcp
```
Then tell the user: type `/mcps`, select **timelinesai**, press **`i`** to sign in. Grok Build does not start sign-in on its own.

### Gemini CLI
```
gemini mcp add --scope user --transport http timelinesai https://mcp.services.timelines.ai/mcp
```
If sign-in is needed, run `/mcp auth timelinesai` inside Gemini CLI. Check with `gemini mcp list`. OAuth needs a local browser, so it will not work over plain SSH or in a container.

### Claude (web or desktop)
You cannot click through the UI. Tell the user: in claude.ai go to Customize, then Connectors, then Add custom connector, paste `https://mcp.services.timelines.ai/mcp`, and sign in with TimelinesAI. Then continue at step 3.

### ChatGPT
Tell the user to open the TimelinesAI plugin in ChatGPT, click Connect, and sign in with TimelinesAI:
https://chatgpt.com/plugins/plugin_asdk_app_6a26d97bd46081918642a70d07cf07d4
Then continue at step 3.

### Any other client
Add `https://mcp.services.timelines.ai/mcp` as a remote (Streamable HTTP) server and sign in when prompted. If the client only supports stdio, use `npx -y mcp-remote@latest https://mcp.services.timelines.ai/mcp --host 127.0.0.1`.

## 3. Load the tools

Refresh the client's tool or server list and look for the `timelinesai` tools.

If they do not appear, the client must reload. In Claude Code this is always needed after adding a server. Tell the user:

> Start a new session in this project (or restart the client), then paste the same setup prompt again. It will pick up where this one stopped.

Stop here and wait. Do not try to verify in the current session. When you run again in the new session, step 1 finds the server already configured, so go straight to step 4.

## 4. Sign in and verify

If the server shows "Needs authentication" (`claude mcp list` in Claude Code), sign-in has not happened yet and its tools will not load. Claude Code does not open the browser on its own for this route. Tell the user to authorize it: run `/mcp` in a terminal `claude` session and pick timelinesai, or click **Reconnect timelinesai** in the desktop app. In Codex and Grok Build use the sign-in command from step 2. The user signs in to TimelinesAI in the browser tab. If they have no account, they can create one on that page (free trial, no card). Pause until they confirm, then continue.

Then call the read-only tool `workspace_whatsapp_accounts`. It proves the connection works and lists QR-connected numbers. WhatsApp Business API (WABA) numbers are listed separately, so if it returns an empty list, also call `waba_accounts` before deciding that no number is connected. Do not call `workspace_quotas` unless a call fails with a quota error, or the user asks.

Read the result and take exactly one branch:

| Result | Meaning | What you do |
|---|---|---|
| At least one connected number (QR or WABA) | Ready | Report success (step 5). |
| Both tools work, but both lists are empty | New user, no number yet | Tell the user to connect a number: open https://app.timelines.ai/whatsapp/all (sidebar: WhatsApp Accounts), click **Connect whatsapp account** and scan the QR code. For a WhatsApp Business API number go to https://app.timelines.ai/waba/accounts/ (sidebar: WhatsApp Business) instead. Pause, then call `workspace_whatsapp_accounts` and `waba_accounts` again. Most tools return empty results until a number is connected. |
| `403 quota_exceeded` (plan limit for API calls) | Setup worked, the workspace is capped | Report setup as done, and that the plan limit is reached. Call `workspace_quotas` once to show the numbers. Point the user to their TimelinesAI plan or billing page, or support. Do not retry in a loop. |
| Auth error or sign-in loop | OAuth not completed | Ask the user to sign in again. If it repeats, report the exact error. |
| Tool not found | Tools not loaded | Go back to step 3. |

## 5. Report

Reply with only verified facts:

- Client and config location edited (or "custom connector, added by user")
- Tools loaded: yes/no
- Signed in: yes/no
- Connected WhatsApp numbers: count, or the error code
- Reload needed: yes/no
- Anything still blocked, and what the user must do

## Safety

WhatsApp sends are immediate and cannot be undone. Keep human confirmation on for any send. To draft without sending, ask for drafts saved as private notes.