warp-mcp

MCP server for the Ringer WARP platform — SIP trunking, phone numbers, porting, messaging/10DLC, billing, and CDR analytics.

Gives AI agents (Claude, Cursor, Copilot, Codex, ChatGPT) full access to the WARP Customer API: 135 tools covering trunk provisioning, number search and ordering, port-in lifecycle, 10DLC brand/campaign registration, SMS sending, invoices, and call-detail analytics.

Quick Start

# Recommended: global install — the setup wizard runs automatically
npm install -g warp-mcp

# Or run the wizard explicitly / without installing
npx -y warp-mcp setup

The wizard validates your API key, stores it in ~/.warp-mcp/config.json, and registers the server with every MCP client it detects (Claude Code, Claude Desktop, Cursor, Codex, GitHub Copilot, ChatGPT Desktop).

You need a WARP API key (rk_...) — mint one in the WARP portal under Settings → API Keys.

One-command installs

Claude Code

claude mcp add -s user warp -e WARP_API_TOKEN=rk_your_key -- npx -y warp-mcp

Cursor — click to install (then replace YOUR_WARP_API_KEY)

Manual (any MCP client)

{
  "mcpServers": {
    "warp": {
      "command": "npx",
      "args": ["-y", "warp-mcp"],
      "env": { "WARP_API_TOKEN": "rk_your_key" }
    }
  }
}

See INSTALL.md for per-client walkthroughs, troubleshooting, and uninstall steps.

Tools

| Prefix | Group | Tools | What it does | |---|---|---:|---| | trunk_ | SIP Trunks | 24 | Trunk CRUD, SIP credentials, endpoints, IP ACLs, registrations | | port_ | Porting | 33 | Port-in requests end to end: draft → validate → submit → activate, documents, TIN compliance | | msg_ | Messaging | 33 | Send SMS, message history, 10DLC brands/campaigns, number enrollment, TCR reference data | | num_ | Numbers | 15 | Search, order, release DIDs; per-TN voice/SMS config; port-out PINs | | team_ | Team | 9 | Members and RBAC roles | | bill_ | Billing | 5 | Balance, ledger, invoices (JSON + HTML) | | cdr_ | Analytics | 5 | Call detail records, statistics, trends, CSV export | | acct_ / net_ / key_ | Account | 10 | Capacity, utilization, scopes, WARP network IPs, API-key audit | | warp_status | Diagnostics | 1 | Config + connectivity check |

The server also ships a warp-guide prompt (and server instructions) with deep WARP domain knowledge — workflows, concepts, and common mistakes.

Environment variables

| Variable | Default | Purpose | |---|---|---| | WARP_API_TOKEN | — | API key (rk_...). Overrides ~/.warp-mcp/config.json | | WARP_API_BASE_URL | https://api.warp.ringer.tel | API base URL override | | WARP_REQUEST_TIMEOUT_MS | 30000 | Per-request timeout |

Token resolution order: env var → ~/.warp-mcp/config.json → unauthenticated (tools return guidance to run setup).

Development

npm ci --ignore-scripts
npm run build   # tsc → dist/
npm test        # vitest (in-memory MCP transport)
npm run dev     # tsx src/index.ts

Releases are published from CI: npm version patch|minor|major, push with --follow-tags, create a GitHub release — the workflow publishes to npm (OIDC trusted publishing with provenance) and to the MCP Registry (io.github.ringer/warp). Do not run npm publish locally after the initial release.

License

MIT © Ringer