Skip to main content
Glama
1msg MCP

1msg MCP

Official
by 1msg
README.md
# @1msg/mcp

MCP server for the [1MSG](https://1msg.io) WhatsApp Business API — **62 public tools** for Cursor, Claude Desktop, and other [MCP](https://modelcontextprotocol.io/) clients.

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

|           |                                                        |
| --------- | ------------------------------------------------------ |
| **npm**   | [`@1msg/mcp`](https://www.npmjs.com/package/@1msg/mcp) |
| **Cloud** | https://mcp.1msg.io/mcp                                |
| **SDK**   | [`@1msg/sdk`](https://www.npmjs.com/package/@1msg/sdk) |

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)

```bash
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

```bash
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
```

## 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:

```json
{
  "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](https://mcp.1msg.io/mcp)

```json
{
  "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

```bash
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`

```bash
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](./ARCHITECTURE.md).

## License

MIT

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