WhatsApp MCP by TimelinesAI

io.github.InitechSoftwarePublished by GitHub account InitechSoftwarev1.0.2Updated Oct 25, 2026

Ask questions across your WhatsApp inbox from Claude, ChatGPT, Cursor or any MCP client.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

A hosted MCP server that connects an AI assistant to a TimelinesAI WhatsApp inbox so it can read, reply to, label and assign chats as you.

What you can do
Discover and read chats and messages, with filters by status, label, assignee, phone and date, for both QR-connected numbers and WhatsApp Business API numbers, plus message details and history paging. Send messages, threaded replies and emoji reactions, including cold sends to a new phone number. Triage chats by opening, closing, assigning or unassigning them and adding or removing labels. Work with WABA templates: list approved templates, inspect their components and send them, and check whether a chat's service window is open. Inspect the workspace: plan, seats, quotas and billing period, connected WhatsApp accounts, and teammates with roles and emails.
When to use it
Useful when a team runs its WhatsApp customer conversations through TimelinesAI and wants an assistant to summarize what needs a reply, draft and send responses, or sort chats by label and assignee from a prompt. It suits both QR-connected numbers and WhatsApp Business API numbers.
Requirements
A TimelinesAI account with at least one connected WhatsApp number in the workspace; without one, most tools return empty results or errors. A remote MCP client that supports Streamable HTTP, connected to the hosted endpoint and signed in once through OAuth in a browser. No API keys or installation; the optional plugin route needs Node.js 18+.
Before you install
This controls a real inbox with no sandbox: writes are immediate, have no undo, and recipients cannot tell messages came from an assistant. Actions run with your TimelinesAI role permissions. Sending draws from the same monthly messaging quota as the UI, and WABA template sends through waba_start_chat and waba_chat_send_template are billed by Meta. Confirm before bulk actions.

Installation

In SourceWeft

  1. Open WhatsApp MCP by TimelinesAI in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.InitechSoftware%2Fwhatsapp-mcp-by-timelinesai/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "whatsapp-by-timelinesai": {
      "type": "http",
      "url": "https://mcp.services.timelines.ai/mcp"
    }
  }
}

README

WhatsApp MCP by TimelinesAI

Run your team's WhatsApp inbox from Claude, ChatGPT, Cursor or any AI assistant.

[License: MIT] [MCP] [Works with Claude] [Works with ChatGPT] [Works with Cursor] [smithery badge]

Connect your TimelinesAI WhatsApp inbox to Claude, ChatGPT, Cursor, Codex, Grok or any MCP client. Ask what needs a reply, then reply, react, label and assign chats from a prompt. 34 tools, all running as you, for both regular WhatsApp numbers and WhatsApp Business API (WABA) numbers.

Included in every TimelinesAI plan at no extra charge. Website · Setup guide · MCP Academy

What is this?

The TimelinesAI MCP server is a remote control for your real WhatsApp inbox inside TimelinesAI. Connect once with your TimelinesAI login, then your AI assistant gains 34 tools across chat discovery, messaging, triage (labels + assignments) and workspace introspection, for both regular WhatsApp numbers (connected by QR code) and WhatsApp Business API (WABA) numbers.

It's a hosted server: nothing to install, no API keys. Your assistant connects to https://mcp.services.timelines.ai/mcp and you sign in once.

No sandbox. Writes are real and visible to your contacts. Recipients cannot tell whether a message came from the UI or from an AI assistant: it's all just you.

Requirements

  • A TimelinesAI account with at least one connected WhatsApp number in your workspace. Without a connected number, most tools return empty results or errors. The MCP is a remote control for your real inbox, not a sandbox.
  • An AI assistant that supports remote MCP servers (all the clients below do).

Don't have a TimelinesAI account yet? Start a 10-day free trial →

Quick setup (~1 min)

Server URL for every client: https://mcp.services.timelines.ai/mcp

ChatGPT

Open the TimelinesAI plugin in ChatGPT, click Connect and sign in with your TimelinesAI account. Then ask: "@TimelinesAI what needs me today?"

Claude (claude.ai and Claude Desktop)

In Claude, open Customize → Connectors → Add custom connector, paste the server URL and sign in with your TimelinesAI account.

Claude Code

bash
claude mcp add --transport http timelinesai https://mcp.services.timelines.ai/mcp

Claude Code opens a browser tab the first time a tool is used. Sign in with your TimelinesAI account.

Prefer a plugin? /plugin marketplace add InitechSoftware/whatsapp-mcp-by-timelinesai, then /plugin install timelinesai-whatsapp@timelinesai. The plugin launches a local proxy, so it needs Node.js 18+; the command above doesn't.

Cursor

Add to Cursor (one click), or add this to ~/.cursor/mcp.json:

json
{  "mcpServers": {    "timelinesai": {      "url": "https://mcp.services.timelines.ai/mcp"    }  }}

The sign-in window opens on the first tool call.

Codex

Add to ~/.codex/config.toml:

toml
[mcp_servers.timelinesai]url = "https://mcp.services.timelines.ai/mcp"

Then run codex mcp login timelinesai once and approve in the browser. Codex doesn't start the sign-in on its own.

Grok Build

bash
grok mcp add timelinesai https://mcp.services.timelines.ai/mcp

Then type /mcps, select timelinesai and press i to sign in. Grok Build doesn't start the sign-in on its own.

Any other MCP client

Add https://mcp.services.timelines.ai/mcp as a remote server (Streamable HTTP) and sign in when prompted.

See examples/ for ready-to-copy config files.

First thing to try

After connecting, ask your assistant:

"What needs me today?"

or, for a tour:

"What tools does the timelinesai MCP server expose? Group them by purpose and give me one example prompt per group."

Tool catalog (34 tools)

Two parallel sets of tools (one for regular WhatsApp numbers connected by QR code, one for WhatsApp Business API (WABA) numbers) plus three workspace tools shared by both. Use the set that matches the number: workspace_whatsapp_accounts lists QR numbers, waba_accounts lists WABA numbers.

GroupTools
Workspace (shared)3
WhatsApp: QR-connected numbers14
WhatsApp Business API (WABA)17
Total34

Workspace: 3 tools

Read-only introspection. Cheap to call. Shared by both sets.

ToolPurpose
workspace_quotasCurrent plan, seats, messaging + API call quotas, billing period
workspace_whatsapp_accountsConnected QR WhatsApp accounts (id, phone, owner, status)
workspace_teamTeammates, roles, invitation status, account bindings. Use for assign emails in both sets

WhatsApp (QR-connected numbers): 14 tools

Chat discovery + inspection: 4 tools

Browse and read. No writes.

ToolPurpose
list_chatsFilter chats by status, labels, assignee, group/direct, phone, name, dates, WA account. Paginated 50/page
chat_detailsFull metadata for a single chat
chat_historyList messages in a chat. Filter by date and direction, page with message-UID cursors
message_detailsInspect a single message
Messaging writes: 4 tools

Quota-consuming. Same monthly messaging budget as the TimelinesAI UI.

ToolPurpose
chat_send_messageSend a message (text, attachment, or reply) in an existing chat
whatsapp_account_send_messageSend a message to any phone via a specific WA account (creates the chat if none exists: a cold send)
message_replyThreaded reply to a specific message
message_reactSet or clear an emoji reaction on a message
Chat mutations: 6 tools

State + triage operations on chats. Idempotent label and assign ops.

ToolPurpose
chat_openReopen a closed chat
chat_closeClose a chat
chat_assignAssign chat to a teammate by email (use workspace_team to discover emails)
chat_unassignUnassign current responsible teammate
chat_set_labelAdd a label to a chat
chat_remove_labelRemove a label from a chat

WhatsApp Business API (WABA): 17 tools

Accounts + chat discovery: 5 tools

Browse and read. No writes.

ToolPurpose
waba_accountsWABA numbers you can send from. Use id as waba_account_id
waba_list_chatsWABA chats you can see. Filter by open/closed, assignee, WABA account, phone; 50/page. Check service_window_is_open before sending
waba_chat_detailsOne WABA chat: service window, assignment, labels, WABA account
waba_chat_historyMessages in a WABA chat, newest first. Filter by date and direction, page with message-UID cursors
waba_message_detailsInspect one WABA message; failed sends include failure_reason
Templates: 2 tools
ToolPurpose
waba_templatesMessage templates you can use, 50/page. Only APPROVED templates can be sent
waba_template_detailsOne template's components, status, and the WABA accounts it can be sent from. Call before any template send
Messaging writes: 4 tools

Template sends incur a Meta charge. Free text only works while the chat's service window is open.

ToolPurpose
waba_start_chatStart a new chat with a phone number using an approved template. Meta charge
waba_chat_send_messageFree-text message in an existing WABA chat, only while service_window_is_open is true
waba_chat_send_templateSend an approved template in an existing WABA chat: the way to message when the service window is closed. Meta charge
waba_message_reactSet or clear an emoji reaction on a WABA message
Chat mutations: 6 tools

State + triage operations on WABA chats. After any mutation, waba_chat_details returns the authoritative state.

ToolPurpose
waba_chat_openReopen a closed WABA chat
waba_chat_closeClose a WABA chat
waba_chat_assignAssign a WABA chat to a teammate by email (from workspace_team)
waba_chat_unassignClear the WABA chat's assignee
waba_chat_set_labelAdd a label, keeping existing labels
waba_chat_remove_labelRemove one label, keeping the others; no-op if the label isn't on the chat

→ Full schemas and example prompts: docs/tools.md

How sign-in works

The server uses OAuth. The first time your assistant connects, a browser window opens on TimelinesAI. Sign in to your TimelinesAI account and approve access. Your assistant keeps the sign-in, so later sessions reconnect without asking.

If you're already signed in to TimelinesAI in your browser, approval can take a single click.

Every action runs as you: your role's permissions in TimelinesAI apply to MCP calls exactly as they apply to UI actions.

Safety + production behavior

⚠️ This MCP server controls a real WhatsApp inbox. Read this section before sending writes.

  • Messages sent via MCP are indistinguishable from messages sent in the UI. Recipients cannot tell.
  • Writes are real and immediate. No undo. Confirm before bulk actions.
  • Quota is shared with UI usage: MCP messages draw from the same monthly messaging budget. Call workspace_quotas to see headroom.
  • WABA template messages are charged by Meta. waba_start_chat and waba_chat_send_template send approved templates, which Meta bills for. Free-text waba_chat_send_message only works while the chat's service window is open.
  • No sandbox mode. Practice on your own number first if you're unsure.
  • Without a connected WhatsApp number, most tools return empty results or errors. Connect a number in TimelinesAI first.

Get started

  1. Start a 10-day free trial of TimelinesAI →
  2. Connect a WhatsApp number in the TimelinesAI dashboard.
  3. Pick your assistant above and connect it.
  4. Sign in, then ask: "What needs me today?"

Links

License

MIT © 2026 Initech Software / TimelinesAI

Source: README.md at commit 35d4f78

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

2
  1. v1.0.2LatestOct 8, 2026
  2. v1.0.1Sep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts