How do I install the senderZ MCP server for Claude Code?

Run 'claude mcp add senderz -- npx @senderz/mcp --api-key YOUR_KEY' in your terminal. The server downloads and runs automatically. You just need a senderZ API key from the developer portal.

Can the senderZ MCP server send iMessages from Claude Code?

Yes. The MCP server's send_message tool supports iMessage, SMS, and auto-routing. When you set the channel to 'auto', senderZ delivers via iMessage when the recipient supports it and falls back to SMS otherwise.

Is the senderZ MCP server free to use?

The MCP server package itself is free and included with all senderZ plans. You need an active senderZ subscription (Starter, Growth, or Scale) or an active free trial to use it, as it requires a valid API key.

Does the senderZ MCP server enforce compliance rules?

Yes. All messages sent through the MCP server go through the same compliance pipeline as the REST API. Opt-out checks, quiet hours enforcement, and phone warming limits are all applied automatically. You cannot accidentally message an opted-out number.

What AI tools and assistants are compatible with the senderZ MCP server?

The MCP server follows the Model Context Protocol standard and works with any MCP-compatible client. It is primarily tested and optimized for Claude Code, but other MCP clients can connect to it as well.

MCP Server | senderZ Docs

Send messages, manage contacts, and check usage directly from Claude Code with the official senderZ MCP server.

The @senderz/mcp package is an official Model Context Protocol server that turns senderZ into a set of tools inside Claude Code. Once installed, you can send messages, manage contacts, check delivery status, and monitor usage using natural language — no code required. No other messaging platform offers an MCP server.

Installation

Add the senderZ MCP server to Claude Code with a single command:

claude mcp add senderz -- npx @senderz/mcp --api-key sz_live_YOUR_KEY

If you are running a self-hosted senderZ instance, pass your custom API URL:

claude mcp add senderz -- npx @senderz/mcp --api-key sz_live_YOUR_KEY --base-url https://api.yourdomain.com

Use an environment variable for your API key

For security, set your API key as an environment variable instead of passing it on the command line. The MCP server reads SENDERZ_API_KEY automatically when no --api-key flag is provided.

export SENDERZ_API_KEY=sz_live_YOUR_KEY
claude mcp add senderz -- npx @senderz/mcp

After installation, restart Claude Code. The senderZ tools will be available immediately.

What You Can Do

Here are real examples of what you can say to Claude Code once the MCP server is installed:

Sending messages:

“Send a verification code to +15551234567”
“Text +15559876543 saying their appointment is confirmed for tomorrow at 2pm”
“Send my ‘welcome_message’ template to these 5 numbers: +1555…, +1555…, …”

Checking status:

“Show me all messages that failed to deliver this week”
“What’s the status of message 01ABC123?”
“How many messages did I send today?”

Managing contacts:

“Add John Smith (+15551234567) to my contacts”
“List all contacts in the ‘VIP Clients’ group”
“Search my contacts for anyone named Garcia”

Compliance:

“Check if +15551234567 has opted out”
“How many messages do I have left this month?”

Templates:

“Create a template called ‘appointment_reminder’ that says: Hi {{name}}, your appointment is on {{date}} at {{time}}.”
“List all my marketing templates”

Webhooks:

“Register a webhook at https://myapp.com/hooks/senderz for delivery events”
“List my active webhooks”
“Remove the webhook for https://old-url.com/hooks”

Tool Reference

The MCP server exposes 12 tools that map directly to the senderZ REST API. Each tool validates your API key before executing.

send_message

Send an iMessage or SMS to a single phone number.

Parameter	Type	Required	Description
`to`	string	Yes	E.164 phone number (e.g. `+15551234567`)
`channel`	string	No	`auto`, `imessage`, or `sms`. Defaults to `auto`.
`body`	string	No	Message text. Use this or `template`, not both.
`template`	string	No	Template name (e.g. `otp_verify`). Use this or `body`.
`data`	object	No	Template variables (e.g. `{ "code": "483920" }`)

get_message

Get the current status of a previously sent message.

Parameter	Type	Required	Description
`message_id`	string	Yes	The message ID returned when the message was sent

list_messages

List sent and received messages with optional filters.

Parameter	Type	Required	Description
`limit`	number	No	Results per page. Default 20, max 100.
`status`	string	No	Filter: `queued`, `sent`, `delivered`, `failed`, `received`
`channel`	string	No	Filter: `imessage` or `sms`
`since`	string	No	ISO date or shorthand: `today`, `7days`, `30days`

list_contacts

List contacts from your contact book.

Parameter	Type	Required	Description
`group`	string	No	Filter by contact group name
`search`	string	No	Search by name or phone number
`limit`	number	No	Results per page

create_contact

Add a new contact to your contact book.

Parameter	Type	Required	Description
`phone_number`	string	Yes	E.164 phone number
`name`	string	No	Contact display name
`group`	string	No	Group to add the contact to

check_optout

Check whether a phone number has opted out.

Parameter	Type	Required	Description
`phone_number`	string	Yes	E.164 phone number to check

get_usage

Get your current billing period usage. No parameters required. Returns messages sent, new contacts used, and plan limits.

list_templates

List all message templates in your account.

Parameter	Type	Required	Description
`type`	string	No	Filter: `otp`, `alert`, or `marketing`

create_template

Create a reusable message template.

Parameter	Type	Required	Description
`name`	string	Yes	Template slug (e.g. `otp_verify`)
`body`	string	Yes	Template body with `{{variable}}` placeholders
`type`	string	Yes	`otp`, `alert`, or `marketing`
`channel`	string	Yes	`imessage`, `sms`, or `both`

list_webhooks

List all registered webhooks for your tenant. No parameters required.

register_webhook

Parameter	Type	Required	Description
`url`	string	Yes	Your webhook endpoint URL (HTTPS required)
`events`	array	Yes	Events to subscribe to (e.g. `["message.delivered", "message.failed"]`)

unregister_webhook

Remove a registered webhook.

Parameter	Type	Required	Description
`webhook_id`	string	Yes	The webhook ID to remove

Authentication

The MCP server authenticates every tool call using the API key you provided during installation. The key is stored in your Claude Code MCP configuration and is never logged or exposed in tool outputs.

If your API key is revoked or expires, tool calls will return an INVALID_API_KEY error. Generate a new key in the developer portal and update your MCP configuration:

claude mcp remove senderz
claude mcp add senderz -- npx @senderz/mcp --api-key sz_live_NEW_KEY

Error Handling

When a tool call fails, the MCP server returns structured errors that Claude can understand and explain to you in plain language:

Error Code	Meaning	What Claude Will Say
`OPTED_OUT`	Recipient has opted out	”That number has opted out of messages. You cannot send to them.”
`QUOTA_EXCEEDED`	Monthly new contact limit reached	”You’ve hit your plan limit. Consider upgrading to send to more new contacts.”
`MISSING_TEMPLATE_VAR`	Template variable not provided	”The template needs a `{{code}}` variable. What value should I use?”
`INVALID_API_KEY`	API key invalid or revoked	”Your API key is not working. Generate a new one in the developer portal.”
`TRIAL_EXPIRED`	Free trial ended without subscription	”Your trial has ended. Subscribe to a plan to continue sending messages.”

Safety Considerations

The MCP server is a powerful tool — it can send real messages to real phone numbers. Keep these guidelines in mind:

Use test numbers during development. Before giving Claude Code access to your production API key, test with internal phone numbers to make sure your prompts produce the intended results.
Review before bulk sends. When you ask Claude to send messages to multiple recipients, it will confirm the recipient list and message content before executing. Always review this confirmation.
Compliance is automatic. The MCP server goes through the same compliance pipeline as the REST API. Opt-out checks, quiet hours, and phone warming limits are all enforced. You cannot accidentally message an opted-out number through the MCP server.
API key scope. The MCP server has the same permissions as your API key. It cannot access other tenants’ data or perform admin operations unless you provide an admin key (which you should not do in MCP).

Updating

The MCP server is distributed via npm. To update to the latest version:

claude mcp remove senderz
claude mcp add senderz -- npx @senderz/mcp@latest --api-key sz_live_YOUR_KEY

Or if you are using the SENDERZ_API_KEY environment variable:

claude mcp remove senderz
claude mcp add senderz -- npx @senderz/mcp@latest

Frequently Asked Questions

Do I need to install anything besides the MCP server? No. The npx @senderz/mcp command downloads and runs the server automatically. You do not need to install the senderZ SDK or any other package. You just need a senderZ API key from the developer portal.

Can I use the MCP server with other AI assistants? The MCP server follows the Model Context Protocol standard. Any MCP-compatible client can use it, though it is primarily tested and optimized for Claude Code.

Does the MCP server work with the self-hosted version of senderZ? Yes. Pass your custom API URL with the --base-url flag during installation and the MCP server will connect to your self-hosted instance instead of api.senderz.com.

Is there a rate limit on MCP tool calls? MCP tool calls go through the same API and are subject to the same rate limits as direct REST API calls. For most use cases, this is not a concern.

Can I use the MCP server to manage webhooks and templates? Yes. The MCP server includes tools for creating templates, registering webhooks, and removing webhooks. You can manage your entire senderZ configuration from Claude Code without touching the REST API or developer portal.