TimelinesAI now exposes a Model Context Protocol (MCP) server, which lets AI assistants like Claude, ChatGPT, and others read and act on your WhatsApp inbox directly — list chats, search messages, send replies, add labels, assign teammates, check quotas, and more.

This article walks you through connecting TimelinesAI to the most popular AI assistants.

Before you start

You need a TimelinesAI account with at least one connected WhatsApp account in your workspace. The MCP controls your real inbox — if no WhatsApp account is linked, the assistant will have nothing to work with. The MCP is available on all TimelinesAI plans.
All actions performed through the MCP run as you: messages you send this way are identical to messages sent from the TimelinesAI UI, and they consume your workspace's monthly messaging quota. Read and action calls also count against your workspace's API calls limit.
The MCP uses standard OAuth — you log in with your regular TimelinesAI credentials. No API token or copy-pasting required.

MCP endpoint: https://mcp.services.timelines.ai/mcp

What the assistant can see and do

The MCP connector respects your existing TimelinesAI permissions. The assistant acts as you, and it can only see and touch what your account is allowed to see and touch in the UI:

Your role in TimelinesAI	What the assistant can access
Owner / Admin	All chats across all WhatsApp accounts in the workspace
Team Supervisor / Teammate	All chats in the WhatsApp accounts that belong to your team
Agent	Only chats in WhatsApp accounts you connected yourself, plus any chats explicitly assigned to you in other accounts

If the assistant says it can't find a chat or returns an empty list, the first thing to check is whether your account actually has visibility over that chat in the TimelinesAI UI.

Option 1 — Claude (web & desktop)

Claude supports remote MCP servers on Pro, Team, and Enterprise plans.

Open Claude in your browser (or the Claude desktop app).
Go to Settings → Connectors.
Click Add custom connector.
Fill in:
- Name: TimelinesAI
- Remote MCP server URL: https://mcp.services.timelines.ai/mcp
Click Add. Claude opens a TimelinesAI login page — sign in and authorize access.
Back in Claude, start a new chat and make sure the TimelinesAI connector is toggled on (look for it in the attachments/tools menu below the message box).

Try it: "List my 5 most recent unread WhatsApp chats."

Note: If you don't see Connectors in settings, your plan or admin policy may not allow custom MCP servers. Ask your Claude workspace admin to enable them.

Option 2 — ChatGPT

ChatGPT supports custom MCP connectors on Plus, Pro, Business, and Enterprise plans.

Open ChatGPT and go to Settings → Connectors (or Settings → Beta features → Connectors, depending on your plan).
Click Create (or Add custom connector).
Fill in:
- Name: TimelinesAI
- MCP server URL: https://mcp.services.timelines.ai/mcp
- Authentication: OAuth
Save. ChatGPT redirects you to TimelinesAI — log in and approve.
Start a new chat, open the tools / connectors menu under the prompt box, and enable TimelinesAI for that conversation.

Try it: "Show me all unread WhatsApp chats assigned to me that haven't been replied to in 24+ hours."

Note: ChatGPT Business/Enterprise workspaces: your ChatGPT workspace admin (not your TimelinesAI admin) may need to approve custom connectors before individual users can add them. This is a ChatGPT-side policy.

Option 3 — Claude Desktop, Cursor, and other local clients

If you use Claude Desktop, Cursor, Windsurf, or any MCP-compatible local client, add this block to your MCP config file:

"timelinesai": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote@latest",
    "https://mcp.services.timelines.ai/mcp",
    "--host", "127.0.0.1"
  ]
}

Important: keep --host 127.0.0.1 exactly as shown. Do not replace it with localhost — the OAuth callback won't resolve and the connection will fail.

Config file locations:

Claude Desktop: Settings → Developer → Edit Config → claude_desktop_config.json
Cursor: Settings → MCP → Edit mcp.json (or ~/.cursor/mcp.json)
Windsurf / other: check your client's MCP documentation

Requirements:

Node.js 18+ installed (Claude Desktop and Cursor use npx under the hood — run node -v to check)

After saving, fully quit and reopen the client. A browser tab will open on first use — log in to TimelinesAI to authorize.

Explore what's possible

Once connected, the simplest way to discover what you can do is to ask the assistant itself:

Tip: "What tools does the TimelinesAI connector expose? Group them by purpose and give me one example prompt per group."

You'll get a personalized tour covering:

Chats — list, search, open, close, assign, label, read history
Messages — send, reply, react, look up details
Workspace — quotas, team members, WhatsApp accounts

Useful starter prompts

"Summarize what happened in my WhatsApp inbox today."
"Find all chats with label lead that haven't been replied to this week and draft a follow-up for each."
"Reply to the last message from [contact name] saying I'll get back to them tomorrow."
"Show me all chats assigned to [teammate] that are still open after 3 days."
"How much messaging quota do I have left this month?"

Things to know

Permissions are enforced. The assistant only sees chats your TimelinesAI role grants you access to (see the table above). It cannot escalate privileges or reach outside your team's WhatsApp accounts.
Messages are real. Anything the assistant sends goes to the actual recipient's WhatsApp. Preview and confirm before bulk actions — "Draft the replies first and show me before sending" is a good habit.
Every sent message consumes messaging quota (1 unit for text, 2 for messages with attachments). Every tool call — including reads like listing chats or pulling history — also consumes API calls quota; a single tool call may translate into several API calls under the hood, so heavy operations can burn through the allowance faster than expected. Ask "How much messaging and API quota is left?" (or call workspace_quotas directly) before bulk operations.
Revoking access: remove the connector from your AI assistant's settings. The TimelinesAI access token used by the connector is short-lived, so once you remove it on the assistant side no further calls can be made under that grant — it will expire on its own shortly after.

Troubleshooting

"No tools available" / connector greyed out

Make sure the connector is toggled on for the current chat (many clients require enabling it per conversation).
Re-authorize: remove the connector and add it again.

OAuth login loop or invalid_scope error

Clear your browser cookies for mcp.services.timelines.ai and app.timelines.ai, then reconnect.

Assistant says "no WhatsApp accounts found" or "no chats"

Confirm at least one WhatsApp number is connected and active at app.timelines.ai → WhatsApp Accounts.
Check your role — if you're an Agent, you'll only see chats in the WhatsApp accounts you connected yourself, plus any chats explicitly assigned to you elsewhere. Ask an Admin to connect more accounts or reassign chats if needed.

Claude Desktop / Cursor: connector not appearing after config edit

Fully quit the app (not just close the window) and relaunch. On macOS, use Cmd+Q; on Windows, exit from the system tray.

Quota exhausted mid-task

Messaging quota: the workspace owner can top up at app.timelines.ai/account/subscription — choose Pay-As-You-Go for a one-time boost or Recurring for ongoing higher limits. If you're not the owner, ask them to top up or upgrade the plan.
API calls quota: if you hit the API calls ceiling, slow down bulk operations or contact support — the limit is per-workspace per-month and resets on the 1st.

Got feedback?

This is a new integration and we're actively expanding what the MCP can do. If you hit a rough edge or want a capability that's missing, reach out to support — your feedback shapes the roadmap.

Unable to Connect your Pipedrive Account with TimelinesAI

TimelinesAI WhatsApp tool in HubSpot Breeze Agents

Cancel TimelinesAI subscription

Connect TimelinesAI to your AI assistant (MCP)