ManyContacts.com MCP for WhatsApp Business

# ManyContacts MCP Server MCP (Model Context Protocol) server for [ManyContacts](https://manycontacts.com) — the WhatsApp Business CRM. Enables AI agents (Claude, Cursor, Windsurf, etc.) to manage contacts, send WhatsApp messages, run campaigns, configure AI auto-replies, and perform all CRM operations programmatically. ## Quick Start ### 1. Get your CLI token ```bash npm install -g @manycontacts/cli ``` **Already have an account?** Log in: ```bash mc auth login --email [email protected] --password mypassword mc auth whoami # verify it works ``` **New to ManyContacts?** Create an account and connect your WhatsApp channel: ```bash # Register a new account mc auth register --email [email protected] --name "My Company" # Connect a WhatsApp Business channel (choose one method): mc channels connect whatsapp-api # WhatsApp Cloud API (recommended) mc channels connect coexistence # ManyContacts coexistence mode mc channels connect qr # QR code pairing # Verify everything is set up mc auth whoami mc channels list ``` ### 2. Configure in your MCP client #### Claude Desktop / Claude Code Add to your MCP settings (`~/.claude/claude_desktop_config.json` or similar): ```json { "mcpServers": { "manycontacts": { "command": "npx", "args": ["@manycontacts/mcp"], "env": { "MC_CLI_TOKEN": "your-cli-token-here" } } } } ``` #### Cursor Add to `.cursor/mcp.json`: ```json { "mcpServers": { "manycontacts": { "command": "npx", "args": ["@manycontacts/mcp"], "env": { "MC_CLI_TOKEN": "your-cli-token-here" } } } } ``` > **Tip:** If you've already logged in via the CLI (`mc auth login`), the token is stored in `~/.manycontacts/config.json` and the MCP server will pick it up automatically — no `MC_CLI_TOKEN` env var needed. --- ## Available Tools (47 total) ### Account & Context #### `manycontacts_context` Get a full overview of your ManyContacts account: connected WhatsApp Business channels, contact/user/tag counts, active AI agents, and enabled features. **Use this first** to understand the account state before performing other operations. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_org_get` Get WhatsApp Business organization/account information including name, timezone, and all configuration settings. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_org_update` Update organization-level settings such as timezone, auto-reply messages, auto-close behavior, and webhook configuration. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `timezone` | `string` | No | Timezone identifier (e.g. `Europe/Madrid`, `America/New_York`) | | `auto_reply_open` | `boolean` | No | Enable auto-reply when a new chat is opened | | `auto_reply_open_text` | `string` | No | Auto-reply message text when chat opens | | `auto_reply_close` | `boolean` | No | Enable auto-reply when a chat is closed | | `auto_reply_close_text` | `string` | No | Auto-reply message text when chat closes | | `auto_reply_close_minutes` | `number` | No | Minutes of inactivity before auto-close | | `auto_reply_away` | `boolean` | No | Enable away/out-of-hours auto-reply | | `auto_reply_away_text` | `string` | No | Away auto-reply message text | | `webhooks_forward` | `boolean` | No | Enable webhook forwarding to an external URL | | `webhooks_forward_url` | `string` | No | External URL to forward webhook events to | --- #### `manycontacts_org_schedule_get` Get the business hours schedule. Returns the configured working hours for each day of the week, used to determine when the "away" auto-reply activates. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_org_apikey` Get the organization's REST API key for direct API integrations. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_channels_list` List all connected WhatsApp Business and Instagram channels. For WhatsApp channels, shows the phone number and connection status. For Instagram channels, shows the username. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- ### Contacts All contact operations use phone numbers as identifiers (with country code, no `+` prefix, e.g. `34600000000`). #### `manycontacts_contacts_list` List WhatsApp Business contacts with advanced filters. Returns paginated results with `has_more` indicator. Filters can be combined freely. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | `number` | No | Page number (default: `1`) | | `limit` | `number` | No | Results per page, max `200` (default: `50`) | | `open` | `"true"` \| `"false"` | No | Filter by conversation open/closed status | | `assigned_to` | `string` | No | Filter by assigned user ID | | `tags` | `string` | No | Comma-separated tag IDs — contacts must have **all** specified tags | | `team` | `string` | No | Filter by team ID | | `stages` | `string` | No | Comma-separated funnel stage IDs | | `date_from` | `string` | No | Filter contacts updated after this date (`YYYY-MM-DD`) | | `date_to` | `string` | No | Filter contacts updated before this date (`YYYY-MM-DD`) | | `unread` | `"true"` | No | Only contacts with unread messages | | `blacklist` | `"true"` | No | Only blacklisted contacts | | `scheduled` | `"true"` | No | Only contacts with pending scheduled messages | > **Note:** When using `date_from` and `date_to` together, the range cannot exceed 90 days. **Response:** ```json { "ok": true, "data": [ { "name": "John Doe", "number": "34600000000", "open": true, "last_user_id": "uuid-of-assigned-user", "source": "whatsapp", "notes": "VIP customer", "customFields": {}, "createdAt": "2026-01-15T10:30:00Z" } ], "pagination": { "page": 1, "limit": 50, "has_more": true } } ``` --- #### `manycontacts_contacts_get` Get detailed information about a specific contact including their tags, teams, funnel stages, and custom fields. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number with country code (e.g. `34600000000`) | --- #### `manycontacts_contacts_create` Create a new WhatsApp Business contact in the CRM. The phone number will be normalized automatically (leading `+` removed). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number with country code (e.g. `34600000000`) | | `name` | `string` | No | Contact display name | | `notes` | `string` | No | Free-text notes for the contact | --- #### `manycontacts_contacts_update` Update an existing contact's name, notes, or custom fields. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact to update | | `name` | `string` | No | New contact name | | `notes` | `string` | No | New contact notes | | `customFields` | `string` | No | Custom fields as a JSON string (e.g. `'{"company":"Acme"}'`) | --- #### `manycontacts_contacts_delete` Permanently delete a contact from the CRM. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact to delete | --- #### `manycontacts_contacts_assign` Assign a contact to a specific team member. The assigned user will see this contact in their personal inbox. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `userId` | `string` | **Yes** | User ID to assign the contact to (use `manycontacts_users_list` to get IDs) | --- #### `manycontacts_contacts_unassign` Remove the current user assignment from a contact. The contact returns to the general unassigned inbox. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | --- #### `manycontacts_contacts_close` Close a WhatsApp conversation. Closed conversations are archived and won't appear in the active inbox. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | --- #### `manycontacts_contacts_open` Reopen a previously closed WhatsApp conversation. The contact will appear again in the active inbox. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | --- #### `manycontacts_contacts_tag_add` Add a tag to a contact. Use `manycontacts_tags_list` to get available tag IDs. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `tagId` | `string` | **Yes** | Tag ID to add | --- #### `manycontacts_contacts_tag_remove` Remove a tag from a contact. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `tagId` | `string` | **Yes** | Tag ID to remove | --- #### `manycontacts_contacts_team_add` Add a team to a contact. Use `manycontacts_teams_list` to get available team IDs. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `teamId` | `string` | **Yes** | Team ID to add | --- #### `manycontacts_contacts_team_remove` Remove a team from a contact. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `teamId` | `string` | **Yes** | Team ID to remove | --- #### `manycontacts_contacts_set_stage` Move a contact to a specific stage within a sales funnel/pipeline. Use `manycontacts_funnels_list` to get funnel and stage IDs. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `funnel_id` | `string` | **Yes** | Funnel ID | | `stage_id` | `string` | **Yes** | Target stage ID within the funnel | --- #### `manycontacts_contacts_bulk` Perform bulk operations on multiple contacts at once. Supports closing, opening, assigning, tagging, and team assignment. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | `"close"` \| `"open"` \| `"assign"` \| `"add_tag"` \| `"add_team"` | **Yes** | Bulk action to perform | | `phones` | `string` | **Yes** | Comma-separated phone numbers (e.g. `"34600000000,34600000001"`) | | `value` | `string` | No | Value required by the action: user ID for `assign`, tag ID for `add_tag`, team ID for `add_team`. Not needed for `close` or `open`. | --- ### Messaging #### `manycontacts_messages_list` List WhatsApp conversation messages for a contact. Returns messages in a conversation-friendly format with timestamps, status, and sender information. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `page` | `number` | No | Page number (default: `1`) | | `limit` | `number` | No | Messages per page (default: `50`) | --- #### `manycontacts_messages_send_text` Send a WhatsApp text message to a contact. Only works within the 24-hour conversation window. Use `manycontacts_messages_send_template` to initiate conversations outside this window. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number to send the message to | | `body` | `string` | **Yes** | Message text content | --- #### `manycontacts_messages_send_note` Create an internal note on a contact's conversation. Notes are only visible to team members and are **not** sent to the WhatsApp contact. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number of the contact | | `body` | `string` | **Yes** | Internal note text | --- #### `manycontacts_messages_send_template` Send a WhatsApp Business template message. Templates are required to initiate conversations outside the 24-hour window or for bulk outbound messaging. Templates must be pre-approved by Meta. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `phone` | `string` | **Yes** | Phone number to send the template to | | `templateId` | `string` | **Yes** | Template ID (use `manycontacts_templates_list` to get IDs) | | `variables` | `string` | No | Template variables as a JSON array string (e.g. `'["John","20%"]'`) | --- ### Templates WhatsApp Business templates are pre-approved message formats required for outbound messaging outside the 24-hour conversation window. #### `manycontacts_templates_list` List all WhatsApp Business message templates. Shows template name, code, status, components, and media flags. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `status` | `"approved"` \| `"pending"` \| `"rejected"` | No | Filter templates by approval status | --- #### `manycontacts_templates_get` Get full details of a specific template including its components (header, body, footer, buttons), configuration, and media attachments. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | Template ID | --- #### `manycontacts_templates_sync` Sync WhatsApp Business templates from Meta Cloud API. Fetches the latest templates from the connected WhatsApp Business account. Useful after creating or modifying templates in the Meta Business Manager. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- ### Campaigns Campaigns allow bulk sending of WhatsApp template messages to a list of phone numbers at a scheduled time. #### `manycontacts_campaigns_list` List all WhatsApp Business bulk messaging campaigns with statistics (sent, delivered, read, and failed counts), template names, and scheduled dates. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_campaigns_create` Create a new WhatsApp Business bulk messaging campaign. The campaign will send a template message to the specified phone numbers at the scheduled time. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | `string` | **Yes** | Campaign name | | `templateId` | `string` | **Yes** | WhatsApp template ID to use (must be `approved`) | | `phones` | `string` | **Yes** | Comma-separated phone numbers (e.g. `"34600000000,34600000001,34600000002"`) | | `date` | `string` | **Yes** | Scheduled send date in ISO format (e.g. `"2026-12-01T09:00:00"`) | | `variables` | `string` | No | Template variables as a JSON array string (e.g. `'["John","20%"]'`) | --- #### `manycontacts_campaigns_delete` Delete a WhatsApp Business campaign. Only pending (not yet sent) campaigns can be deleted. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | Campaign ID to delete | --- ### Tags Tags are colored labels used to categorize and filter WhatsApp Business contacts (e.g. "VIP", "Support", "Lead"). #### `manycontacts_tags_list` List all available tags with their names, colors, and IDs. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_tags_create` Create a new tag for categorizing contacts. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | `string` | **Yes** | Tag name | | `color` | `string` | No | Tag color as hex code (e.g. `"#ff0000"`). Defaults to `#fab1a0` | --- #### `manycontacts_tags_update` Update an existing tag's name or color. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | Tag ID to update | | `name` | `string` | No | New tag name | | `color` | `string` | No | New tag color as hex code | --- #### `manycontacts_tags_delete` Delete a tag. The tag will be removed from all contacts that have it. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | Tag ID to delete | --- ### Teams Teams group users together for assignment routing and contact organization. #### `manycontacts_teams_list` List all teams in the organization. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_teams_create` Create a new team. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | `string` | **Yes** | Team name | --- #### `manycontacts_teams_add_member` Add a user to a team. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `teamId` | `string` | **Yes** | Team ID | | `userId` | `string` | **Yes** | User ID to add to the team | --- #### `manycontacts_teams_remove_member` Remove a user from a team. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `teamId` | `string` | **Yes** | Team ID | | `userId` | `string` | **Yes** | User ID to remove from the team | --- #### `manycontacts_teams_delete` Delete a team. Team members are not deleted, only the team grouping. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | Team ID to delete | --- ### Sales Funnels / Pipelines Funnels allow you to track contacts through a multi-stage sales or support pipeline (e.g. "New Lead" -> "Qualified" -> "Proposal" -> "Won"). #### `manycontacts_funnels_list` List all sales funnels/pipelines with their stages. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_funnels_create` Create a new sales funnel/pipeline. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | `string` | **Yes** | Funnel name | --- #### `manycontacts_funnels_add_stage` Add a new stage to an existing funnel. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `funnelId` | `string` | **Yes** | Funnel ID | | `name` | `string` | **Yes** | Stage name (e.g. "Qualified", "Proposal Sent") | | `order` | `number` | **Yes** | Stage position in the pipeline (0-based) | --- #### `manycontacts_funnels_update_stage` Update a stage's name within a funnel. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `funnelId` | `string` | **Yes** | Funnel ID | | `stageId` | `string` | **Yes** | Stage ID to update | | `name` | `string` | No | New stage name | --- #### `manycontacts_funnels_contacts` List contacts currently in a specific funnel, optionally filtered by stage. Returns paginated results. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `funnelId` | `string` | **Yes** | Funnel ID | | `stage_id` | `string` | No | Filter by specific stage ID | | `page` | `number` | No | Page number | | `limit` | `number` | No | Results per page | --- #### `manycontacts_funnels_delete` Delete a sales funnel/pipeline and all its stages. Contacts in the funnel are not deleted. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | Funnel ID to delete | --- ### Users / Team Members Manage the team members who have access to the WhatsApp Business CRM. #### `manycontacts_users_list` List all team members/users in the organization with their roles and details. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_users_get` Get details of a specific team member. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | User ID | --- #### `manycontacts_users_update` Update a team member's profile information. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | User ID to update | | `name` | `string` | No | New user display name | --- #### `manycontacts_users_invite` Invite a new team member to the organization by email. They will receive an invitation email to join. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `email` | `string` | **Yes** | Email address to send the invitation to | --- #### `manycontacts_users_delete` Remove a team member from the organization. Their assigned contacts will become unassigned. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | User ID to remove | --- ### AI Agents AI agents auto-respond to incoming WhatsApp messages using configurable instructions and scenarios. Only active agents are listed. #### `manycontacts_ai_agents_list` List all active AI auto-reply agents with their configuration. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | *(none)* | — | — | No parameters needed | --- #### `manycontacts_ai_agents_get` Get full details of a specific AI agent including its scenarios (conversation flows), instruction blocks, and configuration. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | AI Agent ID (UUID) | --- #### `manycontacts_ai_agents_update` Update an AI agent's configuration. You can enable/disable the agent or modify its instruction blocks. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | AI Agent ID (UUID) | | `active` | `boolean` | No | Enable (`true`) or disable (`false`) the agent | | `block_1` | `string` | No | Agent instructions — block 1 | | `block_2` | `string` | No | Agent instructions — block 2 | | `block_3` | `string` | No | Agent instructions — block 3 | --- #### `manycontacts_ai_agents_feedback` Get feedback and conversation logs for an AI agent. Shows how the agent has been responding and user satisfaction data. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | `string` | **Yes** | AI Agent ID (UUID) | --- ## Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `MC_CLI_TOKEN` | Yes* | ManyContacts CLI authentication token. Get one via `mc auth login`. | | `MC_API_URL` | No | API base URL (default: `https://api.manycontacts.com`) | > *If you've logged in via the CLI, the token is stored locally at `~/.manycontacts/config.json` and the MCP server reads it automatically. ## Authentication The MCP server authenticates using CLI tokens. Each token is scoped to an organization and has configurable permissions. ```bash # Login to get a token mc auth login --email [email protected] --password mypassword # The token is stored at ~/.manycontacts/config.json # Or set it explicitly via environment variable: export MC_CLI_TOKEN=your-token-here ``` ## Rate Limits - **Paying accounts:** 60 requests/minute - **Free/trial accounts:** 10 requests/minute When rate limited, the server returns a `429` error with a link to upgrade. ## License MIT