spix-mcp

spix-mcp

MCP server for Spix — give any MCP-compatible AI client a phone number, an inbox, and a voice.

   

spix-mcp is a standalone Model Context Protocol server that exposes Spix's communications infrastructure — phone calls, email, contacts, analytics — as MCP tools and resources.

Connect it to Claude Desktop, Cursor, or any MCP-compatible client and your AI can literally pick up the phone.

---

Install

# via pip
pip install spix-mcp

# via uvx (no install needed)
uvx spix-mcp

The Spix CLI must also be installed and authenticated:

curl -fsSL https://spix.sh/install.sh | sh
spix auth login

---

Quick setup: Claude Desktop

The fastest way — use the built-in installer from the Spix CLI:

spix mcp install claude

This writes the correct config to ~/Library/Application Support/Claude/claude_desktop_config.json automatically. Restart Claude Desktop and Spix tools appear immediately.

Or configure manually in claude_desktop_config.json:

{
  "mcpServers": {
    "spix": {
      "command": "uvx",
      "args": ["spix-mcp"],
      "env": {
        "SPIX_API_KEY": "spix_live_sk_your_key_here"
      }
    }
  }
}

Get your API key from app.spix.sh/settings/api-keys.

---

Quick setup: Cursor

spix mcp install cursor

Or add to your Cursor MCP config manually with the same JSON structure as above.

---

What your AI can do

Once connected, your AI client has access to 43 tools (safe profile) or 49 tools (full profile) across all Spix capabilities:

Phone calls

| Tool | Description | |------|-------------| | spix_call_create | Make an outbound AI phone call | | spix_call_show | Get call status and metadata | | spix_call_list | List recent calls | | spix_call_transcript | Get full call transcript | | spix_call_summary | Get call summary + extracted fields | | spix_call_cancel | Cancel an in-progress call (full profile) |

Email

| Tool | Description | |------|-------------| | spix_email_send | Send an email from your Spix inbox | | spix_email_reply | Reply to a received email | | spix_email_list | List emails in your inbox |

SMS

| Tool | Description | |------|-------------| | spix_sms_send | Send an SMS message | | spix_sms_list | List SMS messages | | spix_sms_thread | Get an SMS conversation thread |

Playbooks

| Tool | Description | |------|-------------| | spix_playbook_create | Create a call or SMS playbook | | spix_playbook_list | List all playbooks | | spix_playbook_show | Get playbook details | | spix_playbook_update | Update playbook settings | | spix_playbook_clone | Clone an existing playbook | | spix_playbook_pause | Pause a playbook | | spix_playbook_resume | Resume a paused playbook | | spix_playbook_delete | Delete a playbook (full profile) | | spix_playbook_voice_list | List available voices | | spix_playbook_language_list | List supported languages | | spix_playbook_emotion_list | List available emotions | | spix_playbook_rule_add | Add a rule to a playbook | | spix_playbook_rule_list | List playbook rules | | spix_playbook_rule_remove | Remove a playbook rule | | spix_playbook_rule_clear | Clear all playbook rules |

Contacts

| Tool | Description | |------|-------------| | spix_contact_create | Create a contact | | spix_contact_show | Get contact details | | spix_contact_list | List contacts | | spix_contact_history | Get communication history with a contact | | spix_contact_summary | Get AI-generated contact summary | | spix_contact_tag | Add tags to a contact |

Phone numbers

| Tool | Description | |------|-------------| | spix_phone_list | List your phone numbers | | spix_phone_show | Get phone number details | | spix_phone_bind | Bind a number to a playbook | | spix_phone_unbind | Remove a binding | | spix_phone_release | Release a phone number (full profile) |

Auth & API keys

| Tool | Description | |------|-------------| | spix_auth_whoami | Check current authentication | | spix_auth_key_list | List API keys | | spix_auth_key_create | Create a new API key | | spix_auth_key_revoke | Revoke an API key (full profile) |

Billing & analytics

| Tool | Description | |------|-------------| | spix_billing_status | Get billing plan status | | spix_billing_credits | Check credit balance | | spix_billing_credits_history | Get credit usage history | | spix_billing_plan_set | Change billing plan (full profile) |

Webhooks

| Tool | Description | |------|-------------| | spix_webhook_endpoint_create | Register a webhook endpoint | | spix_webhook_endpoint_list | List webhook endpoints | | spix_webhook_subscription_create | Subscribe to events |

---

Resources (readable state)

The MCP server also exposes live-readable resources:

resource://calls/{id}/transcript     — Call transcript
resource://calls/{id}/summary        — Call summary + extraction
resource://sms/{id}/thread           — SMS thread
resource://playbook/{id}             — Playbook details
resource://contact/{id}              — Contact details
resource://contact/{id}/history      — Contact history
resource://phone/{id}/route          — Phone number routing
resource://billing/credits           — Credit balance
resource://billing                   — Billing overview

---

Tool profiles

| Profile | Tools | Description | |---------|-------|-------------| | safe (default) | 43 | Excludes destructive operations: key revoke, phone release, playbook delete, call cancel, plan changes | | full | 49 | All tools including destructive and billing operations |

For production deployments, safe is recommended. Use full only for trusted clients.

---

Configuration

All configuration is via environment variables:

| Variable | Required | Description | |----------|----------|-------------| | SPIX_API_KEY | Yes | Your Spix API key | | SPIX_DEFAULT_PLAYBOOK | No | Default playbook ID for calls | | SPIX_SESSION_NAME | No | Session name for audit logging | | SPIX_TOOL_PROFILE | No | safe (default) or full |

Scoped access example

Restrict what your agent can access:

{
  "mcpServers": {
    "spix": {
      "command": "uvx",
      "args": ["spix-mcp"],
      "env": {
        "SPIX_API_KEY": "spix_live_sk_your_key_here",
        "SPIX_DEFAULT_PLAYBOOK": "plb_call_abc123",
        "SPIX_SESSION_NAME": "sales-bot",
        "SPIX_TOOL_PROFILE": "safe"
      }
    }
  }
}

---

Example: Ask Claude to make a call

Once configured, you can ask Claude (or any connected client) directly:

"Call +19175550123 using the prospect-qualifier playbook and tell me what they said."

Claude will use spix_call_create, monitor the call, then call spix_call_summary to return the result — without you writing any code.

---

How it works

Your Agent (Claude, Cursor, etc.)
    ↓ MCP tool call
Spix MCP Server (this package)
    ↓ HTTP API call
Spix Backend (api.spix.sh)
    ↓ Carrier APIs
Phone call / Email / SMS

The MCP server is a thin bridge between the MCP protocol and the Spix REST API. All business logic runs server-side.

Voice calls

When your agent calls spix_call_create, Spix:

1. Dials the number via Telnyx/Twilio
2. Uses Deepgram Nova-3 for real-time speech recognition
3. Uses Claude for conversation turn generation
4. Uses Cartesia Sonic-3 for text-to-speech
5. Records the call and generates a transcript + summary

Your agent can then read the transcript and summary via spix_call_transcript and spix_call_summary.

---

Relationship to spix CLI

spix-mcp is the standalone MCP server package. The full Spix CLI includes the MCP server built in (spix mcp serve) alongside all other Spix commands.

Use spix-mcp if you only need the MCP server (e.g. for Claude Desktop integration without installing the full CLI). Use the full CLI if you want all Spix commands available in your terminal.

---

Requirements

• Python 3.10+
• Spix account (free Sandbox for email; Agent plan for calls)
• API key from app.spix.sh

---

Links

• Spix — AI agent communications infrastructure: spix.sh
• Dashboard: app.spix.sh
• Docs — MCP server reference: docs.spix.sh/mcp
• Spix CLI — phone calls, SMS, email from the terminal: Spix-HQ/spix-cli
• PyPI: pypi.org/project/spix-mcp
• Recipes — ready-to-use agent workflows: spix.sh/recipes
• Blog — tutorials and guides: spix.sh/blog
• X/Twitter: @spixhq

---

License

MIT — see LICENSE