> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Control Tuco from Claude Desktop, Cursor, or any MCP-compatible AI agent. Native integration for Tuco AI iMessage automation — works alongside HubSpot.

# MCP Server

The Tuco MCP (Model Context Protocol) Server lets AI assistants manage your iMessage platform using natural language.

## Install

```bash theme={null}
npx tuco-mcp
```

## Configure Claude Desktop

Add this to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "tuco": {
      "command": "npx",
      "args": ["tuco-mcp"],
      "env": {
        "TUCO_API_KEY": "tuco_your_api_key"
      }
    }
  }
}
```

<Info>Get your API key from the **API Keys** tab in the [Tuco dashboard](https://app.tuco.ai/api-keys).</Info>

## Configuration

The server is configured entirely through environment variables (or the matching CLI flags):

| Variable       | Required | Default               | Description                                                                        |
| -------------- | -------- | --------------------- | ---------------------------------------------------------------------------------- |
| `TUCO_API_KEY` | Yes      | —                     | Your workspace API key (`tuco_…`).                                                 |
| `TUCO_API_URL` | No       | `https://app.tuco.ai` | API base URL. Override only if Tuco support points you at a different environment. |

Equivalent flags: `npx tuco-mcp --api-key tuco_your_api_key --api-url https://app.tuco.ai`

<Info>Your API key is tied to one workspace **and** one environment — the `TUCO_API_URL` must match the environment the key was issued for.</Info>

## Available Tools

| Tool                 | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `send-imessage`      | Send an iMessage to any phone number                    |
| `add-lead`           | Add a new contact to your workspace                     |
| `check-imessage`     | Check if a number has iMessage                          |
| `check-replies`      | List recent unread replies                              |
| `list-conversations` | Browse inbox conversations (e.g. those needing a reply) |
| `suggest-reply`      | Draft AI reply options for a conversation               |
| `send-reply`         | Send a reply within a conversation                      |
| `lines-health`       | Monitor all sending line health status                  |
| `check-limits`       | View line limits and current usage                      |
| `list-campaigns`     | View campaigns with status and stats                    |
| `check-health`       | Verify API connection status                            |

## Example Prompts

Once connected, just talk to your AI assistant:

* "Send an iMessage to +12125551234 saying Hey, wanted to follow up on our call"
* "Check if +19042956129 has iMessage enabled"
* "Show me all conversations that need a reply"
* "Draft and send a reply to the latest message from +15551234567"
* "How are my sending lines doing?"
* "Show me the last 5 unread replies"
* "Add a lead: John Doe, +15551234567, CEO at Acme Corp"

## Supported Clients

* Claude Desktop
* Cursor
* Windsurf
* Any MCP-compatible AI client

## Source Code

[View on npm](https://www.npmjs.com/package/tuco-mcp)