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

• Website: spix.sh
• Dashboard: app.spix.sh
• Docs: docs.spix.sh/mcp
• CLI: Spix-HQ/spix-cli
• PyPI: pypi.org/project/spix-mcp

---

License

MIT — see LICENSE