Tuco MCP Server

The official MCP (Model Context Protocol) server for Tuco — the iMessage automation platform for sales teams.

Control your entire Tuco workspace from Claude, Cursor, Windsurf, or any MCP-compatible AI assistant. Send iMessages, manage campaigns, approve KB auto-replies, monitor your inbox, sync CRMs — all through natural language.

Why Tuco?

Tuco is the only platform that lets you run iMessage outreach campaigns at scale. While everyone else fights over crowded email and LinkedIn inboxes, Tuco gives you a direct line to prospects via iMessage — 98% open rates, real conversations, real replies.

• iMessage campaigns with multi-step sequences, branching logic, AI-generated messages, and stop conditions
• Knowledge Base auto-replies — AI answers inbound questions using your docs (manual, copilot, or autopilot mode)
• Unified inbox for managing all conversations across lines
• HubSpot & GoHighLevel sync — pull contacts, push updates, map properties
• Email bridge — send iMessages by emailing [email protected]
• SMS fallback — automatically falls back to SMS when iMessage isn't available

Quick Start

npx tuco-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tuco": {
      "command": "npx",
      "args": ["tuco-mcp"],
      "env": {
        "TUCO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP settings with the same config format as above.

Get Your API Key

1. Log in at app.tuco.ai
2. Go to Integrations > API Keys
3. Click Create API Key

Available Tools (90)

Campaigns (16 tools)

| Tool | What it does | |------|-------------| | create-campaign | Create a campaign with steps, branches, AI agents, stop rules, send windows, scheduling, and line selection | | edit-campaign | Edit campaign steps, lines, settings, name, or forceAfterReply | | list-campaigns | List all campaigns with status filter | | get-campaign | Get campaign details, steps, and stats | | get-campaign-leads | List leads enrolled in a campaign | | pause-campaign | Pause an active campaign | | resume-campaign | Resume a paused campaign | | cancel-campaign | Cancel a campaign and all pending messages | | add-lead-to-campaign | Enroll a lead into a campaign | | get-campaign-stats | Workspace-level dashboard stats | | export-campaign | Export campaign data as CSV | | export-failed-leads | Export failed/SMS-fallback leads | | simulate-campaign-path | Preview what path a lead would take through branches | | test-campaign-step | Test a single step message with personalization | | get-branch-analytics | Analytics for campaign branch paths | | campaign-timeseries | Daily time-series performance data (sent, opened, replied, failed) |

Campaign Features Supported

• Message steps with delays, personalization variables ({{firstName}}, {{companyName}}), attachments
• Branch steps with conditional routing (replied, no reply for N days, CRM tag added, HubSpot property, GHL activity, custom API)
• AI agent steps — Claude/GPT generates personalized messages per lead with system prompt override
• Stop rules per step — tag, CRM property, replied, HubSpot note, GHL activity, custom API
• Wait conditions — delay, until_tag (wait for CRM tag)
• Reply conditions — keyword matching with goto_step, stop, or tag actions
• SMS fallback per step with custom fallback message
• Send windows — start/end time, timezone, allowed days of week
• Scheduling — send immediately or schedule for a specific date/time

Knowledge Base (11 tools)

| Tool | What it does | |------|-------------| | get-kb | Get KB config (mode, threshold, tone, model) | | update-kb | Update KB settings (mode, threshold, tone, instructions, rate limit) | | list-kb-sources | List all KB sources (URLs, Q&A, docs) | | add-kb-source | Add a URL, custom Q&A, snippet, or document to KB | | rescrape-kb-source | Re-research a KB source | | test-kb-query | Test KB with a sample question | | list-pending-replies | List drafts awaiting approval (copilot mode) | | approve-kb-reply | Approve and send a pending draft | | reject-kb-reply | Reject a pending draft | | edit-and-approve-kb-reply | Edit draft text then approve and send | | kb-analytics | KB usage, confidence distribution, daily counts |

Unified Inbox (8 tools)

| Tool | What it does | |------|-------------| | list-conversations | List conversations with filters (status, tag, owner, custom property, cursor pagination) | | send-reply | Reply to a conversation with optional attachments | | suggest-reply | Get AI-suggested reply options (uses KB context) | | mark-read | Mark conversation as read | | archive-conversation | Archive a conversation | | flag-conversation | Flag/unflag for follow-up | | tag-conversation | Add/remove conversation tags | | list-custom-properties | Discover filterable custom property fields |

Leads (12 tools)

| Tool | What it does | |------|-------------| | add-lead | Add a new contact with tags and list assignment | | search-leads | Search by name, phone, email, or tag | | update-lead | Update lead fields | | check-imessage | Check if a single address has iMessage | | batch-check-imessage | Batch check up to 100 addresses at once | | deep-check-imessage | Deep verification via round-robin line check (rate-limited) | | check-dnc | Check Do Not Contact list | | add-to-dnc | Add to Do Not Contact list | | delete-leads | Delete leads and all related data (irreversible) | | classify-lead | Auto-tag a lead/conversation | | sync-dnc-from-crm | Sync DNC list from HubSpot or GHL | | get-dnc-sync-status | Get DNC sync config and last sync status |

Messaging (8 tools)

| Tool | What it does | |------|-------------| | send-imessage | Send iMessage with scheduling, attachments, SMS fallback, send windows, and personalization | | cancel-lead-messages | Cancel all pending/queued/scheduled messages for a lead | | get-replies | Get replies filtered by campaign, lead, or phone with thread context | | check-replies-for-lead | Check if a specific lead has replied | | send-batch | Send multiple messages in a batch (bulk sends outside campaigns) | | quick-send-to-lead | Quick send to a lead by ID (auto-resolves details) | | list-scheduled-messages | List all scheduled/queued/pending messages | | send-sms-fallback | Manually send SMS via Twilio when iMessage unavailable |

CRM Sync — HubSpot & GoHighLevel (7 tools)

| Tool | What it does | |------|-------------| | sync-crm | Trigger a HubSpot or GHL sync (incremental or full) | | sync-status | Check sync job progress | | list-hubspot-lists | Get HubSpot contact lists for campaign targeting | | push-contact-to-hubspot | Push lead data back to HubSpot | | list-crm-tags | Get available GHL tags | | list-crm-owners | Get CRM owners/assignees | | list-crm-custom-fields | Get CRM custom fields for property mapping |

Lines & Health (4 tools)

| Tool | What it does | |------|-------------| | check-health | Verify API connection | | list-lines | List all phone/email lines with usage stats | | lines-health | Line health, connectivity, spam monitoring | | check-limits | Rate limits and current usage per line |

Workspace & Config (26 tools)

| Tool | What it does | |------|-------------| | ai-usage | Check AI credit balance | | dashboard-stats | Workspace KPIs (sent, delivered, replies) | | list-api-keys | List API keys | | list-lists | List all lead lists | | create-list | Create a new lead list | | delete-list | Delete a list (optionally delete all leads in it) | | list-activities | Recent activity/audit log | | list-integrations | Active integrations | | list-variables | Available personalization variables for campaigns | | line-limits | Plan limits (max phone/email lines, can create more) | | get-reactivation-config | Get reactivation scan settings | | set-reactivation-config | Configure dormant conversation detection | | scan-dormant | Find dormant conversations needing reactivation | | reactivate-dormant | Trigger reactivation for dormant conversations | | list-agent-instructions | List all agent instructions | | get-agent-instruction | Get a specific instruction's configuration | | create-agent-instruction | Create an agent instruction with stages and conditions | | update-agent-instruction | Update instruction configuration | | delete-agent-instruction | Archive an instruction and unenroll all leads | | enroll-in-instruction | Enroll a lead into an agent instruction | | get-agent-settings | Get AI agent system instructions and settings | | update-agent-settings | Update AI agent instructions (mode, model, tone, prompt) | | get-fallback-config | Get SMS fallback/Twilio configuration | | update-fallback-config | Update SMS fallback settings and Twilio credentials |

Example Prompts

Once connected, just talk to your AI assistant:

• "Create a 3-step campaign targeting my 'Q1 Leads' list with a follow-up after 2 days and a branch if they reply"
• "Send an iMessage to +12125551234 saying Hey, wanted to follow up on our call"
• "Show me all conversations that need a reply"
• "Approve the pending KB reply for the lead asking about pricing"
• "Pause the Q1 Outreach campaign"
• "Sync my HubSpot contacts"
• "Check if +15551234567 has iMessage"
• "What replies did I get on my last campaign?"
• "Add a stop rule to step 2: stop if HubSpot lifecycle stage changes to 'customer'"
• "Cancel all pending messages for +19876543210 — they opted out"
• "Set up an AI agent step that uses Claude to personalize messages based on the lead's company"
• "Show me the branch analytics — which path are most leads taking?"
• "Send a batch of messages to these 5 phone numbers"
• "Scan for dormant conversations and reactivate them"
• "Create an agent instruction that follows up until they book a meeting"
• "What scheduled messages are queued to go out?"
• "Sync my DNC list from HubSpot"
• "Show me the daily trend for my campaign over the last 30 days"

Links

• Tuco Website — iMessage automation for sales teams
• Tuco App — Log in to your workspace
• Tuco Docs — Full documentation
• MCP Integration Guide — Setup + reference

License

MIT