MCP Server - Tuco AI

What is the Tuco MCP Server?

The Model Context Protocol (MCP) server lets AI assistants drive your Tuco workspace using natural language. Every tool call hits the same authenticated REST API as the Tuco dashboard, so anything an MCP client does is auditable in the activity log and visible in /analytics. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Installation

npx tuco-mcp

Package: tuco-mcp on npm. 90+ tools across messaging, replies, campaigns, leads, lines, knowledge base, and analytics.

Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

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

Get your API key from Integrations → API Keys in the dashboard.

Core Tools

The MCP exposes the full Tuco surface. The ones you’ll reach for first:

Tool	What it does	Underlying endpoint
`send-imessage`	Send a single iMessage. Supports scheduling, attachments, SMS fallback, send windows.	`POST /api/messages`
`quick-send-to-lead`	Send to an existing lead by `leadId` (auto-resolves contact).	`POST /api/leads/send`
`send-batch`	Send up to 1000 messages in one call.	`POST /api/messages/batch`
`get-replies`	Paginated reply list. Filter by campaign, lead, phone, email, sending line, and a UTC date window.	`GET /api/replies`
`send-reply`	Reply back in a conversation.	`POST /api/unibox/send-reply`
`suggest-reply`	AI-suggested reply options for a conversation (uses KB if configured).	`POST /api/unibox/suggest-reply`
`list-conversations`	Filter the unified inbox by status, tag, owner, custom property.	`GET /api/unibox/conversations`
`analytics`	Reached, sent, SMS fallback, failed, replied, unique repliers, reply %, positive replies, positive %. Filterable by campaign, line, user, date window.	`GET /api/analytics`
`cancel-lead-messages`	Cancel pending/queued/scheduled messages for a lead (e.g. on opt-out).	`POST /api/messages/cancel-for-lead`

See the full list with npx tuco-mcp --help or any MCP client’s tool browser.

Example Prompts

Reply triage and outreach loop:

“Send an iMessage to +12125551234 saying ‘Hey, wanted to follow up’”
“Fetch all replies received on line <lineId> between June 1 and June 10.”
“Show reply rate and positive reply rate for campaign <campaignId> over the last 7 days.”
“List my last 50 unread conversations, then suggest a reply for the top one.”
“Reply ‘Thanks, sending a calendar link now’ to the conversation with +12125551234.”

The get-replies and analytics filters compose, so you can ask things like “What’s the positive reply rate on line X for campaign Y last week, and show me each replier.”

Reply Pagination & Filters

get-replies mirrors the API:

Param	Type	Notes
`campaignId`	string	Restrict to replies from leads in this campaign.
`leadId`	string	A single lead.
`recipientPhone`	string	E.164 or any normalizable format.
`recipientEmail`	string	Exact match.
`lineId`	string	Restrict to replies received on this Tuco line.
`dateFrom` / `dateTo`	ISO 8601	Inclusive UTC window on the reply timestamp.
`page` / `limit`	integer	Default `page=1`, `limit=50`, max `100`.

The response includes total, page, limit, totalPages, and each row carries recentReplies (last 10 inbound) plus parentMessages (recent outbound) so the AI has full thread context without a second call. Full schema, error codes, and an interactive playground are at API → Check Replies.

Analytics from the MCP

The analytics tool returns the same metric block the dashboard /analytics page reads, so the AI’s answer and the UI agree exactly. Definitions, formulas, and the interactive playground live at API → Analytics.

​What is the Tuco MCP Server?

​Installation

​Configuration

​Core Tools

​Example Prompts

​Reply Pagination & Filters

​Analytics from the MCP

​See Also