# atiendo24-mcp-server

[![npm version](https://img.shields.io/npm/v/atiendo24-mcp-server.svg)](https://www.npmjs.com/package/atiendo24-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

MCP server for [Atiendo24](https://atiendo24.com) — control your WhatsApp AI agent platform directly from Claude Desktop.

<img src="https://img.shields.io/badge/MCP-Compatible-blue?logo=anthropic" alt="MCP Compatible" />

## What is this?

This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects Claude Desktop to the Atiendo24 platform. It gives Claude access to 9 tools that let you manage appointments, customers, conversations, leads, analytics, and send WhatsApp messages — all through natural language.

```
You: "How many appointments do I have tomorrow?"
Claude: Uses get_appointments → "You have 3 appointments tomorrow: ..."

You: "Send a WhatsApp to +50688881234 saying the appointment is confirmed"
Claude: Uses send_whatsapp → "Message sent successfully."
```

## Architecture

```
Claude Desktop (or any MCP client)
        ↓ MCP Protocol (stdio)
atiendo24-mcp-server (runs locally)
        ↓                    ↓
   Supabase DB        WhatsApp Cloud API
  (read/write)         (send messages)
```

## Tools

### Read Tools

#### `get_appointments`
Fetches scheduled appointments with filtering options.

| Parameter | Type | Description |
|-----------|------|-------------|
| `filter` | `"today" \| "week" \| "all"` | Time period (default: `"today"`) |
| `client_id` | `string` | Filter by business client ID |
| `status` | `string` | Filter by status: `confirmed`, `completed`, `cancelled`, `no-show` |

**Example prompts:**
- "What appointments do I have today?"
- "Show me all cancelled appointments this week"
- "How many confirmed appointments are there?"

---

#### `get_customers`
Searches the customer database by name, phone, or email.

| Parameter | Type | Description |
|-----------|------|-------------|
| `search` | `string` | Search by name, phone, or email |
| `client_id` | `string` | Filter by business client ID |
| `limit` | `number` | Max results (default: `20`) |

**Example prompts:**
- "Find the customer with phone 8888-1234"
- "Search for Maria Lopez in the database"
- "How many customers do we have?"

---

#### `get_conversations`
Retrieves WhatsApp conversations with status filtering.

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | `"active" \| "escalated" \| "resolved"` | Conversation status |
| `client_id` | `string` | Filter by business client ID |
| `search` | `string` | Search by customer name or phone |
| `limit` | `number` | Max results (default: `20`) |

**Example prompts:**
- "Are there any escalated conversations?"
- "Show me recent active conversations"
- "How many conversations were resolved today?"

---

#### `get_leads`
Fetches sales leads captured by the AI sales agent (Millie).

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | `string` | Lead status: `contacted`, `demo_scheduled`, `proposal_sent` |
| `search` | `string` | Search by name, phone, or business type |
| `limit` | `number` | Max results (default: `30`) |

**Example prompts:**
- "How many leads does Millie have this week?"
- "Show me leads with demos scheduled"
- "Find leads from dental clinics"

---

#### `get_funnel`
Returns the full sales conversion funnel with data quality metrics.

No parameters required.

**Returns:**
- Funnel stages: total leads → contacted → demo scheduled → proposal sent → closed clients
- Conversion rates between each stage
- Data quality: % of leads with valid phone, % with name

**Example prompts:**
- "How's the sales funnel looking?"
- "What's our lead-to-client conversion rate?"
- "What percentage of leads have valid contact info?"

---

#### `get_analytics`
Platform-wide metrics for a given time period.

| Parameter | Type | Description |
|-----------|------|-------------|
| `period` | `7 \| 30 \| 90` | Days to analyze (default: `7`) |
| `client_id` | `string` | Filter by business client ID |

**Returns:**
- Conversations: total, escalated, resolved, resolution rate, escalation rate
- Appointments: total, no-shows, cancelled, no-show rate
- Leads: total count

**Example prompts:**
- "Give me the metrics for the last 30 days"
- "What's the no-show rate this month?"
- "How many conversations were escalated last week?"

---

### Write Tools

#### `create_appointment`
Creates a new appointment after checking availability.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client_id` | `string` | Yes | Business client ID |
| `customer_phone` | `string` | Yes | Customer phone number |
| `customer_name` | `string` | Yes | Customer name |
| `date` | `string` | Yes | Date in `YYYY-MM-DD` format |
| `time` | `string` | Yes | Time in `HH:MM` format |
| `service` | `string` | No | Service requested |
| `duration_minutes` | `number` | No | Duration (default: `60`) |
| `notes` | `string` | No | Additional notes |

**Example prompts:**
- "Schedule an appointment for Juan Perez tomorrow at 10am"
- "Book a dental cleaning for Maria on 2026-05-01 at 14:00"

---

#### `cancel_appointment`
Cancels an existing appointment by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `appointment_id` | `string` | Yes | Appointment ID to cancel |
| `client_id` | `string` | No | Business client ID for verification |

**Example prompts:**
- "Cancel Juan's appointment"
- "Cancel appointment ID abc-123"

---

#### `send_whatsapp`
Sends a WhatsApp message from the Atiendo24 business number.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | `string` | Yes | Destination phone (e.g., `+50688881234` or `88881234`) |
| `message` | `string` | Yes | Message text |

> **Note:** WhatsApp Cloud API requires the recipient to have messaged your number within the last 24 hours. Messages outside this window require pre-approved templates.

**Example prompts:**
- "Send a WhatsApp to +50688881234 saying the appointment is confirmed"
- "Message this prospect that I'll call them tomorrow"

---

## Installation

### Prerequisites

- Node.js >= 18
- A Supabase project with the Atiendo24 schema
- WhatsApp Cloud API credentials (for `send_whatsapp`)

### Setup

```bash
git clone https://github.com/edgarconejo/atiendo24-mcp-server.git
cd atiendo24-mcp-server
npm install
npm run build
```

### Configure Claude Desktop

Add the following to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "atiendo24": {
      "command": "node",
      "args": ["/absolute/path/to/atiendo24-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key",
        "WA_CLOUD_API_TOKEN": "your-whatsapp-cloud-api-token",
        "WA_CLOUD_PHONE_NUMBER_ID": "your-phone-number-id"
      }
    }
  }
}
```

Restart Claude Desktop after saving the config.

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SUPABASE_URL` | Yes | Your Supabase project URL |
| `SUPABASE_SERVICE_ROLE_KEY` | Yes | Supabase service role key (bypasses RLS) |
| `WA_CLOUD_API_TOKEN` | For `send_whatsapp` | WhatsApp Cloud API permanent token |
| `WA_CLOUD_PHONE_NUMBER_ID` | For `send_whatsapp` | WhatsApp Business phone number ID |

### Verify Installation

After restarting Claude Desktop, click the **+** button in a new chat → **Connectors** — you should see "atiendo24" listed and enabled.

Try asking: *"How many appointments do I have today?"*

## Tech Stack

- **Runtime:** Node.js
- **MCP SDK:** [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
- **Database:** [Supabase](https://supabase.com) (PostgreSQL)
- **Messaging:** [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api) (Meta Graph API v21.0)
- **Language:** TypeScript

## About Atiendo24

[Atiendo24](https://atiendo24.com) is a multi-tenant SaaS platform that deploys AI-powered WhatsApp agents for businesses in Costa Rica. Each agent handles customer inquiries, schedules appointments, sends reminders, and processes payments — 24/7.

Built with Next.js, Supabase, Claude API, and WhatsApp Cloud API.

## License

MIT