npm package: @inbounter/mcp
Description: Inbounter MCP server — connect any MCP client to the Inbounter email & SMS API
Latest version: 1.0.0

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://inbounter.com/logos/inbounter_light.svg" />
    <source media="(prefers-color-scheme: light)" srcset="https://inbounter.com/logos/inbounter_dark.svg" />
    <img src="https://inbounter.com/logos/inbounter_dark.svg" alt="Inbounter" width="300" />
  </picture>
</p>

<p align="center">
  <b>Official MCP Server for <a href="https://inbounter.com">Inbounter</a></b><br/>
  Give AI assistants the power to manage inboxes, messages, and routing via the Model Context Protocol.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@inbounter/mcp">
    <img src="https://img.shields.io/npm/v/@inbounter/mcp.svg?style=flat-square" alt="NPM Version" />
  </a>
  <a href="https://github.com/inbounter/inbounter-mcp/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/inbounter/inbounter-mcp.svg?style=flat-square" alt="License" />
  </a>
</p>

# Inbounter MCP Server

The Inbounter MCP server connects any AI assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io) to the full Inbounter API. Once configured, your AI can create inboxes, read and send email/SMS, manage shield rules, provision phone numbers, wait for incoming messages, and more -- all through natural language.

## What is Inbounter?

**Inbounter** is infrastructure that gives AI agents their own inboxes -- email, SMS, and more -- with built-in security and smart routing.

- 📬 **Inboxes** -- Provision dedicated email & SMS inboxes for AI agents
- 🛡️ **Shield Mode** -- Block spam, phishing, and unwanted messages automatically
- 🔀 **Smart Routing** -- Route inbound messages with filters, AI extraction, and webhooks
- 📨 **Outbound** -- Send emails and SMS directly from agent inboxes
- ⏳ **Waiters** -- Long-poll or callback-based waiting for specific incoming emails (OTPs, magic links, replies)
- 🔗 **Webhooks** -- Real-time event notifications for contacts, messages, and more
- 💳 **Credits** -- Usage-based billing with auto-replenish

> [Get your API key](https://inbounter.com)

## Setup

### Claude Desktop

Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "inbounter": {
      "command": "npx",
      "args": ["@inbounter/mcp"],
      "env": {
        "INBOUNTER_API_KEY": "your-api-key",
        "INBOUNTER_WORKSPACE_ID": "wks_xxx"
      }
    }
  }
}
```

### Cursor

Add the following to your Cursor MCP configuration (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "inbounter": {
      "command": "npx",
      "args": ["@inbounter/mcp"],
      "env": {
        "INBOUNTER_API_KEY": "your-api-key",
        "INBOUNTER_WORKSPACE_ID": "wks_xxx"
      }
    }
  }
}
```

### Other MCP Clients

Any MCP-compatible client can use this server. Run it directly with:

```bash
INBOUNTER_API_KEY=your-api-key INBOUNTER_WORKSPACE_ID=wks_xxx npx @inbounter/mcp
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `INBOUNTER_API_KEY` | Yes | Your Inbounter API key. Get one at [inbounter.com](https://inbounter.com). |
| `INBOUNTER_WORKSPACE_ID` | Yes | Your workspace ID (starts with `wks_`). |
| `INBOUNTER_API_URL` | No | API base URL. Defaults to `https://api.inbounter.com`. |

## Available Tools

This MCP server exposes **28 tools** across 9 categories. Every tool maps directly to the [Inbounter REST API](https://inbounter.com/docs).

### Inbox Management

| Tool | Description |
|---|---|
| `list_inboxes` | List all inboxes in the workspace. |
| `get_inbox` | Get full details and metadata for a single inbox. |
| `create_inbox` | Create a new inbox. Supports both email and SMS channels, with optional Twilio or bridge provider configuration. |
| `update_inbox` | Update inbox settings such as name, description, status, shield rules, or default webhook URL. |
| `delete_inbox` | Permanently delete an inbox. |

### Messages

| Tool | Description |
|---|---|
| `get_messages` | List messages. Pass `inbox` (email address, ID, or an array of either) to filter by inbox, or omit to list across all inboxes. Supports cursor pagination, status filtering, and text search. |
| `get_message` | Get a single message with full delivery details and route runs. |
| `search_messages` | Search messages by query string. Supports `keyword` mode (default) and `semantic` mode for AI-powered relevance ranking. Can filter by inbox. |

### Threads

| Tool | Description |
|---|---|
| `get_threads` | List conversation threads. Optionally filter by one or more inboxes. |
| `get_thread` | Get the full message history within a thread. |

### Sending

| Tool | Description |
|---|---|
| `send_email` | Send a single email from an inbox. If the inbox has approval mode enabled, the email is queued for human review and the tool returns a `QUEUED_FOR_APPROVAL` status. |
| `send_batch` | Send multiple emails from a single inbox in one request. |
| `reply_to_thread` | Reply to the latest message in a thread. Automatically resolves threading headers (`In-Reply-To`, `References`) for proper email threading. Accepts markdown, plain text, or HTML body. |

### Wait for Email

| Tool | Description |
|---|---|
| `wait_for_email` | Wait for a specific email to arrive in an inbox. Checks recent messages first and returns immediately if already present. Supports OTP extraction (4-8 digit codes), magic link detection, and reply matching. Use `timeout_seconds=0` for a non-blocking check. Provide a `callback_url` to receive results asynchronously via POST instead of long-polling. |

### Phone / SMS

| Tool | Description |
|---|---|
| `search_phones` | Search available phone numbers to purchase. Filter by country code and area code. |
| `create_phone` | Purchase and provision a phone number (E.164 format) for SMS. |
| `list_phones` | List all phone numbers assigned to the workspace. |
| `release_phone` | Release a phone number. Includes a 3-day grace period to reclaim. |
| `send_sms` | Send an SMS message from a provisioned phone number. |

### Shield Mode

| Tool | Description |
|---|---|
| `get_shield_rules` | Get the current shield mode state and rules for an inbox. |
| `update_shield_rules` | Replace the shield rules for an inbox. Automatically enables shield mode. |
| `toggle_shield` | Enable or disable shield mode on an inbox without changing the rules. |

### Webhooks

| Tool | Description |
|---|---|
| `get_webhooks` | List all webhooks configured for the workspace. |
| `create_webhook` | Create a new webhook. Specify the target URL, event types to subscribe to, and an optional verification token. |
| `test_webhook` | Send a test event to an existing webhook to verify connectivity. |

### Analytics

| Tool | Description |
|---|---|
| `get_inbox_stats` | Get analytics counters for a specific inbox (messages received, sent, etc.). |
| `get_shield_stats` | Get shield-specific metrics for an inbox: processed count, quarantined count, and rejection rate. |
| `get_workspace_credits` | Get workspace credit balance, auto-replenish settings, and recent transaction ledger. |

## Documentation

Full API documentation is available at [inbounter.com/docs](https://inbounter.com/docs).

## Contributing

Contributions are welcome. Please open an issue or submit a pull request at [github.com/inbounter/inbounter-mcp](https://github.com/inbounter/inbounter-mcp).

## License

MIT -- see [LICENSE](./LICENSE) for details.