Model Context Protocol

Connect NumberClaw to your AI

Model Context Protocol (MCP) lets AI assistants like Claude, Cursor, and Gemini directly manage your phone numbers, send SMS, and more from your AI tool.

Generate API Key Open API Docs

Prerequisites

A NumberClaw account with access to the dashboard.
An API key generated from the API Keys page.

MCP Endpoint

https://app.numberclaw.com/api/v1/mcp

Every setup below uses the same secure endpoint and sends your API key in the `Authorization` header.

Setup Guides

Use the guide that matches your AI tool. Replace `YOUR_API_KEY` with your own NumberClaw token.

Claude.ai

~/.claude/claude_desktop_config.json

1Open Claude Desktop settings and locate the MCP configuration file.
2Add the NumberClaw server entry shown below.
3Save the file and restart Claude Desktop.
4Ask Claude to list your NumberClaw tools to confirm the connection.

Configuration snippet

{
  "mcpServers": {
    "numberclaw": {
      "url": "https://app.numberclaw.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

.cursor/mcp.json

1Open Cursor settings and go to MCP configuration.
2Create or edit `.cursor/mcp.json` in your project or user config.
3Paste the NumberClaw configuration and save the file.
4Reload Cursor, then ask the agent to run `list_my_numbers`.

Configuration snippet

{
  "mcpServers": {
    "numberclaw": {
      "url": "https://app.numberclaw.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

1Open Windsurf settings and find the MCP section.
2Create `~/.codeium/windsurf/mcp_config.json` if it does not exist.
3Paste the configuration below and save it.
4Restart Windsurf and verify NumberClaw appears in the available tools.

Configuration snippet

{
  "mcpServers": {
    "numberclaw": {
      "serverUrl": "https://app.numberclaw.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Gemini

Google AI Studio -> Settings -> MCP

1Open Google AI Studio or the Gemini MCP settings screen.
2Add a new MCP server.
3Use the server URL and header values shown below.
4Save the server and test with a NumberClaw account action like `get_account_balance`.

Configuration snippet

Server URL: https://app.numberclaw.com/api/v1/mcp
Header: Authorization: Bearer YOUR_API_KEY

OpenClaw

~/.openclaw/openclaw.json

1Open your OpenClaw MCP config or create `~/.openclaw/openclaw.json`.
2Add the NumberClaw MCP server entry shown below.
3Save the file so OpenClaw can launch the MCP process with your API key.
4Run a simple command like `search_numbers` to verify the integration.

Configuration snippet

{
  "mcpServers": {
    "numberclaw": {
      "command": "npx",
      "args": ["-y", "@numberclaw/mcp"],
      "env": {
        "NUMBERCLAW_API_KEY": "YOUR_API_KEY",
        "NUMBERCLAW_BASE_URL": "https://app.numberclaw.com/api"
      }
    }
  }
}

Available Tools

Tool	Description
search_numbers	Search for available phone numbers to purchase. Filter by area code, state, type, or vanity pattern.
purchase_number	Purchase/provision a phone number. Returns a Stripe checkout URL to complete payment.
list_my_numbers	List all phone numbers you own in your NumberClaw account.
get_number	Get details for a specific phone number you own.
release_number	Release (cancel) a phone number from your account. This cannot be undone.
send_sms	Send an SMS or MMS message from one of your NumberClaw numbers.
configure_forwarding	Configure call forwarding for a phone number. Activate or deactivate forwarding to a destination phone or SIP URI.
get_call_logs	Retrieve call history for your account or a specific number.
create_marketplace_listing	List one of your phone numbers for sale on the NumberClaw marketplace.
get_valuation	Get an estimated market value for any phone number.
get_account_balance	Get your NumberClaw account billing info: balance, usage, and active subscriptions.

Troubleshooting

Issue	Fix
401 Unauthorized	Check that your API key is valid, copied fully, and still active in NumberClaw.
Connection refused	Verify the MCP URL is exactly https://app.numberclaw.com/api/v1/mcp and that your network allows outbound HTTPS.
Unknown tool	Reload or update your MCP client so it fetches the latest NumberClaw tool manifest.
Tool error: No owned number found	Confirm the number belongs to your account and use the correct E.164 number or NumberClaw number ID.
CORS errors	Configure MCP inside your AI tool or desktop client instead of trying to call the endpoint directly from browser JavaScript.

Ready to get started?

Generate a NumberClaw API key, paste it into your AI tool, and start managing numbers and messaging without leaving your assistant.

Go to API Keys