MCP 服务器

Spix

Give AI agents a real phone number and voice. Make calls, send email, manage contacts — 26 tools, 12 resources.

README

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:

Dials the number via Telnyx/Twilio
Uses Deepgram Nova-3 for real-time speech recognition
Uses Claude for conversation turn generation
Uses Cartesia Sonic-3 for text-to-speech
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.