Skip to main content
Glama
1msg MCP

1msg MCP

Official
by 1msg

@1msg/mcp

MCP server for the 1MSG WhatsApp Business API — 62 public tools for Cursor, Claude Desktop, and other MCP clients.

Transports: stdio (local) and Streamable HTTP (Cloud).

API hosts:

Environment

ONE_MSG_BASE_URL

Live channels

https://api.1msg.io

Test channels

https://sandbox.1msg.io

Source of truth for codegen of tools.generated.ts / handlers.generated.ts still lives in the 1msg-api monorepo (packages/mcp). This repository is the distribution package for running and hosting the server.

Quick start

npx (stdio)

export ONE_MSG_BASE_URL=https://api.1msg.io
export ONE_MSG_INSTANCE_ID=your-instance-id
export ONE_MSG_TOKEN=your-channel-token

npx -y @1msg/mcp
# or, after clone + build:
# pnpm start

For test channels, set ONE_MSG_BASE_URL=https://sandbox.1msg.io (bare sandbox.1msg.io is also accepted).

Clone and run

git clone https://github.com/1msg/1msg-mcp.git
cd 1msg-mcp
pnpm install --frozen-lockfile
pnpm run build

export ONE_MSG_BASE_URL=https://api.1msg.io
export ONE_MSG_INSTANCE_ID=your-instance-id
export ONE_MSG_TOKEN=your-channel-token

pnpm start                 # stdio → dist/index.js
pnpm run start:http        # Streamable HTTP → dist/http.js

Related MCP server: MCP Chat

Environment variables

Variable

Required

Description

ONE_MSG_BASE_URL

yes (stdio)

API root: https://api.1msg.io (live) or https://sandbox.1msg.io (test)

ONE_MSG_TOKEN

yes (stdio)

Channel API token

ONE_MSG_INSTANCE_ID

yes (stdio)

Channel instance id

MCP_HTTP_HOST

no

HTTP bind host (default 0.0.0.0 in Docker)

MCP_HTTP_PORT

no

HTTP port (default 3100)

MCP_RATE_LIMIT_RPM

no

Per-token rate limit for HTTP (default 60)

For Cloud HTTP, the server default upstream is ONE_MSG_BASE_URL (typically live). Clients send credentials per request; test channels can also send X-1msg-Base-Url: https://sandbox.1msg.io.

Cursor (mcp.json)

Local stdio

Live channel:

{
  "mcpServers": {
    "1msg": {
      "command": "npx",
      "args": ["-y", "@1msg/mcp"],
      "env": {
        "ONE_MSG_BASE_URL": "https://api.1msg.io",
        "ONE_MSG_INSTANCE_ID": "your-instance-id",
        "ONE_MSG_TOKEN": "your-channel-token"
      }
    }
  }
}

Test channel: set "ONE_MSG_BASE_URL": "https://sandbox.1msg.io".

Cloud URL (Streamable HTTP)

Cloud endpoint: https://mcp.1msg.io/mcp

{
  "mcpServers": {
    "1msg": {
      "url": "https://mcp.1msg.io/mcp",
      "headers": {
        "Authorization": "Bearer your-channel-token",
        "X-Instance-Id": "your-instance-id"
      }
    }
  }
}

For a test channel, add "X-1msg-Base-Url": "https://sandbox.1msg.io".

Header aliases: X-1msg-Instance-Id (and deprecated X-Chat-Api-Instance-Id). Do not commit real tokens.

Cloud HTTP locally

export ONE_MSG_BASE_URL=https://api.1msg.io
export MCP_HTTP_PORT=3100
pnpm run start:http
  • Auth: Authorization: Bearer <token> + X-Instance-Id: <instanceId>

  • Optional: X-1msg-Base-Url: https://sandbox.1msg.io for test channels

  • Health: GET /healthz, GET /readyz

docker build -t 1msg/1msg-mcp-http:local .
docker run --rm -p 3100:3100 \
  -e ONE_MSG_BASE_URL=https://api.1msg.io \
  1msg/1msg-mcp-http:local

Scripts

Script

Purpose

pnpm run build

Compile TypeScript → dist/

pnpm test

Jest unit tests

pnpm run smoke:tools-list

Stdio tools/list smoke (expects 62 tools; uses dummy token)

pnpm start / pnpm run start:http

Run stdio / HTTP servers

Architecture

All API HTTP goes through @1msg/sdk. See ARCHITECTURE.md.

License

MIT

Available Tools

62 tools
add_templateB

Create a WABA message template (name, category, language, components). After create, Meta reviews the template; list it with GET /templates.

Inputs: name, category, language, components.

block_userC

Block WhatsApp user

Inputs: phone (required).

create_commerceB

Update catalog/cart commerce settings via the params object.

  • params.is_catalog_visible — show catalog storefront icon (true) or hide it (false).

  • params.is_cart_enabled — enable cart (true) or disable it (false).

Blocked when the channel subscription limit is exceeded. Requires a commerce-capable channel (Cloud Functions /commerceWAV2).

Inputs: params (required).

create_flowsB

Create a WhatsApp Flow (name + categories required). Currently returns HTTP 501 until the Meta Graph Flows rewrite is available.

Inputs: name (required), categories (required), publish, flowJson, +2 more.

create_flows_flow_id_deprecateD

Deprecate Flow

Inputs: flowId (required), wabaAccountId.

create_flows_flow_id_publishC

Publish Flow

Inputs: flowId (required), wabaAccountId.

create_groupsD

Create Group

Inputs: groupName (required), description.

create_groups_group_idC

Update group subject, description, and/or profile picture. Path groupId is the WABA group id (without @g.us).

Inputs: groupId (required), subject, description, profile_picture_file.

create_read_messageC

Mark message as read

Inputs: msgId, messageId, typingIndicator.

create_settingsB

Update channel settings. Only send fields you want to change.

webhookUrl replaces the stored list (one URL string, or up to 5 URLs as an array). Passing an empty value clears webhooks. Repeating the same URL(s) also clears a sticky auto-disable. With several URLs, send the complete array to re-enable one of them — omitting a URL removes it from the channel.

Inputs: rawHooks, webhookUrl, guaranteedHooks, ackNotificationsOn, +2 more.

create_upload_mediaA

Upload a file to WhatsApp media storage and get a numeric mediaId for later use with send_file / send_sticker (mediaId field, not body).

Pass the file as body or url — an HTTP(S) URL or a base64 data URI. The mediaId in the response is a numeric string (keep it as a string).

Inputs: url, body.

delete_flows_flow_idD

Delete Flow

Inputs: flowId (required), wabaAccountId.

delete_groups_group_idC

Delete Group

Inputs: groupId (required).

delete_mediaA

Delete previously uploaded media by numeric mediaId (from /uploadMedia).

This is the canonical deletion endpoint and uses the REST DELETE verb on the media resource path. The older POST /deleteMedia is a deprecated alias.

Inputs: mediaId (required).

delete_media_legacyB

Deprecated. Use DELETE /media/{mediaId} instead.

This POST alias is kept for backward compatibility with earlier integrations. New integrations should call DELETE /media/{mediaId}: 1msg follows REST conventions for resource deletion going forward (delete a resource with the DELETE verb on its resource path).

Inputs: mediaId (required).

get_calling_settingsA

Return WhatsApp Calling API settings for this channel (beta).

Proxies upstream GET /calling/settings.

Prerequisites

  • Number must be eligible for Meta Calling (Cloud API; not COEX)

  • Trial / subscriptionBlocked channels receive 403 plain text

  • You need your own WebRTC or SIP stack; 1msg is a signaling proxy only and does not store call history or recordings

See the Calling tag overview for inbound/outbound flows and webhooks.

Inputs: no named parameters.

get_commerceA

Returns catalog/cart commerce settings for the channel.

Fails with a provider error when the WABA has no catalog linked — that is an API/account limitation, not an MCP schema bug.

  • is_catalog_visible — show catalog storefront icon (true) or hide it (false).

  • is_cart_enabled — enable cart (true) or disable it (false).

Inputs: no named parameters.

get_conversational_automationA

Get WhatsApp conversational components for the channel (welcome message, ice-breaker prompts, and slash commands).

Proxies Meta/360dialog GET /conversational_automation.

When enable_welcome_message is true and a user opens chat for the first time, Meta delivers a webhook message with type: request_welcome. The inbound formatter exposes that as type: "request_welcome" and meta.request_welcome: true so your webhook can send a custom welcome reply.

Inputs: no named parameters.

get_flows_flow_idC

Get Flow Details

Inputs: flowId (required), wabaAccountId.

get_flows_flow_id_previewD

Preview Flow

Inputs: flowId (required), wabaAccountId.

get_groups_group_idD

Get Group Info

Inputs: groupId (required), fields.

get_meA

Return the WhatsApp Business profile for this channel: About, address, description, email, phone, websites, industry (vertical), and profile photo URL.

Inputs: no named parameters.

get_mm_lite_statusB

Get MM Lite availability and status

Inputs: no named parameters.

get_statusA

Return WhatsApp Cloud API connection status for this channel (connected when the number can send). May include accountStatus, messaging limit, and MM Lite availability.

Optional health_status_warning appears only when Meta Graph health could not be loaded and a soft connected response is returned. Omitted on the normal path and when health details are not applicable for the channel — never an internal provider/transport name.

Inputs: no named parameters.

get_webhookA

Return the webhook URL(s) currently configured for this channel, plus delivery status for each URL.

webhookUrl is a string when a single URL is set, an array of strings when multiple URLs are configured, or null if none is set.

Prefer webhookStatuses. The circuit breaker is per URL, not per channel. If 1 of 4 URLs is sticky-disabled, that URL is skipped; the other three still receive events. Send/receive are not affected.

Channel-level haveDisabledWebhooks, circuitState, reason, fails, trips, and timestamps are a compatibility summary of one URL (the first sticky-disabled URL, else the first configured URL). They are not "the channel is dead".

  • haveDisabledWebhooks — true when at least one URL in webhookUrl is sticky auto-disabled. Live URLs still get events.

  • circuitState — compressed scalar for that same primary URL: ok | degraded | open | half_open | disabled.

  • disabledWebhooks — currently configured URLs that are sticky-disabled (subset of webhookUrl).

  • webhookStatuses — one row per currently configured URL. Use this array to see which endpoints are live vs skipped.

  • fails / trips / firstFailAt — diagnostics for support, not product UI. fails = failures in a rolling ~10 minute window (not lifetime). trips = failed recovery probes on the 15 min → 1 h → 6 h schedule (sticky disable after 3). Clients can ignore these and use webhookStatuses + disabledWebhooks only.

Sticky disable skips delivery; it does not unconfigure the URL (it stays in webhookUrl). Re-enable with POST /webhook or POST /settings. Those endpoints replace the whole list — with multiple URLs, send the full array.

Inputs: no named parameters.

get_whatsapp_business_encryptionA

Retrieve the WhatsApp business public key and signature status for this channel's phone number. Required before publishing or sending Flows that use data encryption.

Inputs: no named parameters.

initiate_callA

Perform a WhatsApp Calling action (beta).

Proxies upstream POST /calling/calls. Despite the historical path name /initiateCall, this endpoint handles all call actions:

action

Use

Required

connect

Outbound business → user

to + session (sdp_type: offer)

pre_accept

Inbound (optional, reduces audio clipping)

call_id + session (sdp_type: answer)

accept

Inbound answer

call_id + session (sdp_type: answer)

reject

Decline inbound

call_id

terminate

Hang up

call_id

SDP / media (critical)

  • accept / pre_accept require a WebRTC-generated SDP answer.

  • Do not send Meta's offer SDP back as the answer.

  • Postman (or curl) alone cannot establish real media — you need a WebRTC or SIP stack. 1msg only proxies signaling.

Answer within ~30–60 seconds of an inbound connect webhook or Meta terminates as unanswered. Common Meta errors include Calling not enabled (138000), no permission (138006), SDP validation failures.

Outbound requires a prior Call Permission Request (CPR) acceptance. See the Calling tag overview for the full outbound flow and CPR limits.

Trial / subscriptionBlocked → 403 plain text. Upstream failures often return HTTP 200 with { "response": { "error": "<upstream message>" } }. Invalid API KEY is used only when Meta/360 body actually indicates an invalid API key or token. Other upstream 401s (notably call permission 138006) pass through error.message / error_user_msg.

Inputs: action (required), messaging_product (required), to, call_id, +2 more.

list_blocked_usersA

Returns users currently blocked on this WhatsApp channel (WABA GET /block_users). Same channel token auth as blockUser / unblockUser.

Inputs: no named parameters.

list_flowsB

List WhatsApp Flows for the WABA. Currently returns HTTP 501 until the Meta Graph Flows rewrite is available.

Inputs: fields, wabaAccountId.

list_groupsC

List WhatsApp groups for this channel. Paginate with limit, before, and after.

Inputs: after, limit, before.

list_messagesB

List stored chat history for this channel (requires history storage). Filter with chatId, limit, last, message numbers, or time bounds.

Inputs: last, limit, msgId, chatId, +4 more.

list_settingsA

Return channel settings: webhook URL(s), delivery flags, and analytics toggles.

Auto-disable / circuit state matches GET /webhook. Prefer webhookStatuses (one row per configured URL). The breaker is per URL, not per channel.

Channel-level haveDisabledWebhooks is true when at least one URL in webhookUrl is sticky auto-disabled — not "the channel is dead". Live URLs still receive events. Top-level circuitState / reason / fails / trips are a compatibility summary of one URL (first sticky-disabled, else first configured).

This is the same GET /settings endpoint as the REST API (previously missing from MCP).

Inputs: no named parameters.

list_templatesB

List message templates. Paginate with limit / offset; sort by id, name, or status.

Inputs: sort, limit, offset.

patch_flows_flow_id_assetsC

Replace the Flow JSON document (flowJson). Currently returns HTTP 501 until the Meta Graph Flows rewrite is available.

Inputs: flowId (required), flowJson (required), wabaAccountId.

patch_flows_flow_id_metadataA

Update Flow name, categories, and/or endpointUri. Currently returns HTTP 501 until the Meta Graph Flows rewrite is available.

Inputs: flowId (required), name, categories, endpointUri, +1 more.

remove_templateA

Delete a message template by name (all language versions of that name).

Inputs: name (required).

retrieve_mediaA

Get WABA media URL and metadata by mediaId (from uploadMedia). The returned url is temporary and typically expires within ~5 minutes.

Inputs: mediaId (required).

send_address_messageA

Request shipping address from the user (WhatsApp interactive address_message).

India and Singapore only. Requires:

  • Business WhatsApp number registered in that country

  • Recipient phone matching the country (+91 ↔ IN, +65 ↔ SG)

Pass country: "IN" or country: "SG". Eligibility is validated upstream; mismatches (e.g. Singapore phone with country: "IN") return errors such as Unsupported Interactive Message type (HTTP 200 with sent: false).

Optional action parameters: values, saved_addresses, validation_errors.

Inputs: body (required), phone, chatId, values, +4 more.

send_buttonC

Send Reply Buttons Message

Inputs: body, phone, chatId, footer, +4 more.

send_contactB

Send a WhatsApp contact card.

Preferred simple body (legacy-compatible):

{
  "phone": "79001234567",
  "contact": { "name": "Lida", "phone": "+79181976551" }
}

Cloud API shape also works: contacts is an array of objects with name.formatted_name and phones[].phone (E.164 string, not a timestamp).

Inputs: phone, chatId, contact, contacts, +1 more.

send_cta_urlC

Send an interactive message with a single call-to-action URL button.

Inputs: url (required), body (required), displayText (required), phone, +4 more.

send_fileC

Send a file to an existing chat. (Only if the dialogue has an Open Session). Only one of two parameters is needed to determine the destination - chatId or phone.

Inputs: body, phone, voice, chatId, +5 more.

send_flowB

Send Interactive WhatsApp Flow message to an existing chat. (Only if the dialogue has an Open Session). Only one of two parameters is needed to determine the destination - chatId or phone.

Use this method to send a published WhatsApp Flow as a service (interactive) message. If the 24-hour window is closed, send a template with a FLOW button via /sendTemplate.

Inputs: body (required), flowId (required), flowCta (required), flowToken (required), +11 more.

send_listD

Send List Message

Inputs: body, phone, action, chatId, +3 more.

send_locationA

Send a location to an existing chat. (Only if the dialogue has an Open Session). Only one of two parameters is needed to determine the destination - chatId or phone.

Inputs: lat (required), lng (required), name, phone, +3 more.

send_location_requestD

Send Location Request Message

Inputs: body, phone, chatId, quotedMsgId.

send_messageB

Send a message to an existing chat. (Only if the dialogue has an Open Session). The message will be added to the queue for sending and delivered even if the phone is disconnected from the Internet or authorization is not passed.

Only one of two parameters is needed to determine the destination - chatId or phone.

Inputs: body (required), phone, chatId, quotedMsgId.

send_order_detailsA

Send a WhatsApp order details payment / invoice message using a pre-approved Utility template that has an ORDER_DETAILS button.

India only (WhatsApp Payments India). Requires:

  • India WhatsApp Business number

  • Commerce enabled on the channel (GET/POST /commerce)

  • Approved template with an ORDER_DETAILS button

Use this method when you need structured fields (order, referenceId, currency, paymentSettings). The API appends a template button sub_type: order_details and sends via the same path as POST /sendTemplate.

Works outside the 24-hour session window (template message).

You can also send the same payload yourself with POST /sendTemplate by including a button component in params:

{
  "type": "button",
  "sub_type": "order_details",
  "index": 0,
  "parameters": [{
    "type": "action",
    "action": {
      "order_details": {
        "reference_id": "order-123",
        "currency": "INR",
        "order": { "status": "pending", "items": [], "subtotal": { "offset": 100, "value": 50000 } }
      }
    }
  }]
}

Inputs: order (required), language (required), template (required), namespace (required), +6 more.

send_payment_requestB

Send a regional payment request interactive message (beta scaffold). region must be IN, SG, or BR. Payload shape follows Meta regional payments docs; verify on stage before production use. Full regional builders are not implemented yet.

Inputs: phone (required), region (required), body, action, +1 more.

send_productB

Send a single catalog product or a product list. Destination is chatId or phone. action is required:

  • single product: { "catalog_id": "...", "product_retailer_id": "..." }

  • product list: { "catalog_id": "...", "sections": [{ "title": "...", "product_items": [{ "product_retailer_id": "..." }] }] }

Inputs: action (required), body, phone, chatId, +3 more.

send_reactionD

Send Reaction

Inputs: body, phone, chatId, quotedMsgId.

send_stickerC

Send a WhatsApp sticker by mediaId or link URL.

Inputs: link, phone, chatId, mediaId, +1 more.

send_templateA

Send a WhatsApp template message (works outside the 24-hour session window).

Use this tool — not send_message — when the 24h session is closed.

params MUST be Cloud API component objects, never a flat list of strings and never the old On-Prem hsm / localizable_params format.

Example body variable {{1}}:

{
  "type": "body",
  "parameters": [{ "type": "text", "text": "Ivan" }]
}

Do not send "type": "hsm" and do not send params: ["Ivan", "123"].

Supported params button sub_type values include: url, quick_reply, copy_code / coupon_code, catalog, flow, limited_time_offer, and order_details (WhatsApp Payments India only — requires an approved Utility template with an ORDER_DETAILS button).

Convenience wrapper with structured fields: POST /sendOrderDetails.

Inputs: phone, chatId, params, language, +6 more.

set_conversational_automationA

Update WhatsApp conversational components.

Allowed body fields (others are ignored):

  • enable_welcome_message (boolean)

  • prompts (string[], max 4, each ≤ 80 chars)

  • commands ({ command_name, command_description }[])

Proxies Meta/360dialog POST /conversational_automation.

Inputs: prompts, commands, enable_welcome_message.

set_webhookA

Set the client webhook URL that receives inbound events for this channel.

Replaces the stored webhook list (it does not append). To deliver the same events to several endpoints, pass an array in webhookUrl (max 5) or use POST /settings. With several URLs already configured, posting only the disabled URL drops the others — send the complete array to re-enable one of many.

Incoming payloads include messages, delivery ACKs, group updates, coexistence echoes, and calling events. WhatsApp Calling payloads (type: "calls") are documented under the Calling tag. Call permission replies arrive on the normal messages path (call_permission_reply).

Repeating POST /webhook with the same URL(s) clears an auto-disable (self-serve re-enable). Send/receive are not affected by webhook auto-disable.

Inputs: webhookUrl (required).

set_whatsapp_business_encryptionA

Upload and sign a 2048-bit RSA business public key (PEM) for this channel's phone number. Meta requires a signed key before Flow publish/send. Only one active key per number; a new upload replaces the previous key.

Inputs: business_public_key (required).

unblock_userC

Unblock WhatsApp user

Inputs: phone (required).

update_calling_settingsA

Enable, disable, or update WhatsApp Calling settings (beta).

Proxies upstream POST /calling/settings. Body is forwarded as-is (1msg does not validate fields).

Common fields under calling

  • status (ENABLED | DISABLED) — required to turn calling on/off

  • call_icon_visibility (DEFAULT | DISABLE_ALL) — optional

  • callback_permission_status (ENABLED | DISABLED) — optional; when enabled, inbound user calls grant callback permission

  • call_hours — optional hours / timezone object

  • sip — optional SIP trunk; when SIP is ENABLED, Graph call actions and calling webhooks are not used

  • srtp_key_exchange_protocol (DTLS | SDES) — SDES only with SIP

  • video.status — optional

Meta may accept only one feature group per request — prefer focused updates (e.g. enable status first, then SIP).

Trial / subscriptionBlocked → 403 plain text.

Inputs: calling.

update_meB

Update WhatsApp Business Account profile fields. At least one of about, description, email, photo, address, vertical, websites is required. Blocked when the channel subscription limit is exceeded.

Inputs: about, email, photo, address, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 62 tools

    Disambiguation3/5

    Many tools are distinct by message type, but generic send_message overlaps with send_file, send_location, send_contact, etc., and get_webhook/list_settings plus set_webhook/create_settings duplicate webhook/settings behavior. create_groups_group_id sounds like a create operation but actually updates a group, which will mislead selection.

    Naming Consistency3/5

    Most names use snake_case with a verb_noun pattern, but create_ is repeatedly used for update operations (create_settings, create_commerce, create_groups_group_id), and add/remove_template coexists with create/delete conventions elsewhere. Flow tool names also mix verb, resource, id, and action in inconsistent orders.

    Tool Count2/5

    62 tools is excessive for an agent-facing server even for a broad WhatsApp API surface. The set includes deprecated aliases, beta scaffolds, multiple 501 flow tools, and overlapping settings/webhook operations that could be consolidated.

    Completeness3/5

    The surface covers messaging, templates, media, groups, flows, calling, settings, commerce, and profile operations broadly. However, notable gaps remain such as group participant management, template retrieval/update operations, and Flow endpoints that are currently nonfunctional.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients like Claude Code and Cursor to use multiple AI models (Gemini, GPT, Grok, DeepSeek, Kimi, Ollama) via a unified chat tool with conversation memory.
      3
      55 PyPI
      1
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      MCP Chat is a CLI application that enables interactive chat with AI models via the Anthropic API, supporting document retrieval, command-based prompts, and extensible MCP tool integrations.
      2
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes authorized ChatGPT, DeepSeek, Kimi, and Grok web sessions to agents as MCP tools, including chat and local file attachments over HTTP or stdio.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI tools to uniformly discover, inspect, and call tools, prompts, and resources from multiple upstream MCP servers through a small set of fixed MCP tools, over stdio or HTTP.
      2
      MIT