# Ready MCP Server

Send SMS messages from any AI assistant — Claude, ClickUp, Cursor, Windsurf, and more. One-click setup.

[![npm version](https://img.shields.io/npm/v/readysms-mcp.svg)](https://www.npmjs.com/package/readysms-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

## Setup (30 seconds)

### Step 1: Get your API key

1. Create a free account at **[tryready.com](https://tryready.com)**
2. Go to **Settings → API Keys → Create Key**
3. Copy your key (starts with `rsms_`)

### Step 2: Add to your AI tool

Copy-paste the config for your platform:

<details open>
<summary><b>ClickUp (Hosted MCP — one-click)</b></summary>

1. In ClickUp, go to **Apps → MCP Servers → Add Custom MCP Server**
2. Enter:
   - **Name:** Ready
   - **URL:** `https://api.tryready.com/mcp`
   - **Auth:** OAuth 2.0
3. Click **Connect** — you'll be redirected to sign in to Ready and authorize ClickUp
4. Done! Ask ClickUp's AI to send texts, manage campaigns, check delivery rates, etc.

</details>

<details>
<summary><b>ClickUp (Local — alternative)</b></summary>

If you prefer local mode, add as an MCP integration in ClickUp's AI settings:

```json
{
  "mcpServers": {
    "ready": {
      "command": "npx",
      "args": ["-y", "readysms-mcp"],
      "env": {
        "READY_API_KEY": "rsms_your_key_here"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ready": {
      "command": "npx",
      "args": ["-y", "readysms-mcp"],
      "env": {
        "READY_API_KEY": "rsms_your_key_here"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Claude Code (CLI)</b></summary>

```bash
claude mcp add ready -- npx -y readysms-mcp
```

Then set the env var in your shell or `.env`:
```bash
export READY_API_KEY=rsms_your_key_here
```
</details>

<details>
<summary><b>Cursor</b></summary>

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "ready": {
      "command": "npx",
      "args": ["-y", "readysms-mcp"],
      "env": {
        "READY_API_KEY": "rsms_your_key_here"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

Add to `~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "ready": {
      "command": "npx",
      "args": ["-y", "readysms-mcp"],
      "env": {
        "READY_API_KEY": "rsms_your_key_here"
      }
    }
  }
}
```
</details>

### Step 3: Start talking

Just ask your AI assistant naturally:

> "Send a text to +15551234567 saying their appointment is tomorrow at 3pm"

> "Show me my unread conversations"

> "Draft a campaign to remind customers about our summer sale"

> "How many credits do I have left?"

> "Run a deliverability audit on my phone numbers"

## What You Can Do

### Messaging
| Tool | What it does |
|------|-------------|
| `send_sms` | Send an SMS to any phone number |
| `ai_generate_message` | AI-generate 5 message variants from a description |
| `get_message_logs` | View message history with delivery status |

### Inbox
| Tool | What it does |
|------|-------------|
| `list_conversations` | Browse conversations with search and filters |
| `get_messages` | Read a conversation thread |
| `update_conversation` | Mark read/unread, star, archive, close |

### Contacts
| Tool | What it does |
|------|-------------|
| `search_contacts` | Find contacts by name, phone, tag, stage, score |
| `create_contact` | Add a new contact |
| `update_contact` | Update contact info, tags, pipeline stage |
| `list_tags` | See all tags in use |

### Campaigns
| Tool | What it does |
|------|-------------|
| `ai_compose_campaign` | AI-draft a campaign from plain English |
| `create_campaign` | Create a campaign (draft or scheduled) |
| `list_campaigns` | View campaigns with delivery stats |
| `campaign_breakdown` | Detailed performance analytics |
| `diagnose_campaign` | Troubleshoot delivery issues |

### Automation
| Tool | What it does |
|------|-------------|
| `list_drip_sequences` | View automated follow-up sequences |
| `enroll_in_drip` | Enroll contacts in a drip sequence |
| `list_ai_agents` | View AI auto-reply agents |
| `test_ai_agent` | Test an AI agent's reply without sending |

### Analytics & Billing
| Tool | What it does |
|------|-------------|
| `get_balance` | Check credit balance and pricing tier |
| `get_delivery_rate` | Account-wide delivery rates by carrier |
| `check_deliverability` | Per-number health metrics |
| `get_spend_history` | Daily spend breakdown |
| `get_transactions` | Full billing transaction log |
| `list_phone_numbers` | Phone numbers with health status |

### Setup
| Tool | What it does |
|------|-------------|
| `test_connection` | Verify your API key works |

## Built-in Workflows

These pre-built prompts guide your AI through multi-step tasks:

- **`send_campaign`** — Walk through creating a campaign: check balance → AI-draft message → choose audience → save as draft
- **`inbox_summary`** — Summarize unread conversations, flag urgent items, show balance
- **`deliverability_audit`** — Audit every phone number with red/yellow/green health status

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `READY_API_KEY` | Yes | — | Your API key from Ready settings (starts with `rsms_`) |
| `READY_API_URL` | No | `https://api.tryready.com` | API base URL (only change for self-hosted) |

> The legacy `READYSMS_API_KEY` / `READYSMS_API_URL` variables still work — no need to change existing configs.

## Reliability

- **Automatic retries** with exponential backoff on 429/502/503/504
- **30-second timeout** on all API calls (no hanging)
- **Structured errors** — clear, actionable messages (not stack traces)
- **Phone number normalization** — accepts `(555) 123-4567`, `5551234567`, `+15551234567`
- **Input validation** — catches bad inputs before hitting the API
- **Startup validation** — verifies API key format immediately

## Get Started

Don't have a Ready account? **[Sign up free at tryready.com](https://tryready.com)** — takes under 2 minutes.

Need help? Email **support@tryready.com**