# WAzion MCP Server

<!-- TODO: Replace with actual logo -->
<!-- ![WAzion Logo](https://www.wazion.com/assets/logo.png) -->

[![npm version](https://img.shields.io/npm/v/@wazion/mcp-server.svg)](https://www.npmjs.com/package/@wazion/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

Connect your AI assistant to [WAzion](https://www.wazion.com) — the WhatsApp Business platform with AI copilot, automated workflows, mass marketing, CRM, and more. This MCP server exposes **240+ tools** that let any MCP-compatible client manage your WhatsApp Business operations through natural language.

---

## Quick Start

### Method 1: Direct HTTP (recommended — no install needed)

WAzion's MCP endpoint supports [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http), so most clients can connect directly without installing anything.

**Claude Code:**
```bash
claude mcp add --transport http wazion https://www.wazion.com/api/mcp/ \
  --header "Authorization: Bearer YOUR_API_KEY"
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "wazion": {
      "type": "url",
      "url": "https://www.wazion.com/api/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Method 2: npm package (for stdio-only clients)

If your client only supports stdio transport, use the npm package as a bridge:

```bash
npx -y @wazion/mcp-server
```

Requires the `WAZION_API_KEY` environment variable to be set.

---

## Setup by Client

### Claude Code

```bash
claude mcp add --transport http wazion https://www.wazion.com/api/mcp/ \
  --header "Authorization: Bearer YOUR_API_KEY"
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wazion": {
      "type": "url",
      "url": "https://www.wazion.com/api/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### ChatGPT

In ChatGPT settings, go to **Connectors** and add a new Streamable HTTP connection:

- **URL:** `https://www.wazion.com/api/mcp/`
- **Authentication:** Bearer token with your API key

### Cursor

Create or edit `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "wazion": {
      "type": "url",
      "url": "https://www.wazion.com/api/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Windsurf / VS Code

Add to your `settings.json`:

```json
{
  "mcp.servers": {
    "wazion": {
      "type": "url",
      "url": "https://www.wazion.com/api/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Any stdio-only Client

For clients that only support stdio transport (no HTTP), use the npm package:

```bash
WAZION_API_KEY=your_key npx -y @wazion/mcp-server
```

Or in your client's configuration:

```json
{
  "mcpServers": {
    "wazion": {
      "command": "npx",
      "args": ["-y", "@wazion/mcp-server"],
      "env": {
        "WAZION_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

---

## Available Tools

WAzion exposes **244 tools** across 24 categories. Here are the main ones:

| Category | Tools | Description |
|----------|------:|-------------|
| **Mass Marketing** | 39 | WhatsApp bulk campaigns, contact lists, send configuration, unsubscribe management, and campaign statistics |
| **WhatsApp Operations** | 27 | Session status, message logs, send messages, workflow execution, and connection management |
| **Plugins** | 18 | Product Q&A, web chat, document Q&A — install, configure, and monitor plugins |
| **Automation** | 16 | WhatsApp Auto workflows — create triggers, conditions, AI replies, and scheduled messages |
| **Statistics** | 15 | Conversation metrics, response times, agent performance, and usage analytics |
| **General Settings** | 13 | Language, timezone, date format, Shopify integration, and business preferences |
| **Customers** | 13 | Customer info, notes, tags, search, alerts, and conversation history |
| **AI Prompt** | 12 | System prompt, custom instructions, AI model settings, and response behavior |
| **Storage** | 12 | Upload, list, delete, and manage files in cloud storage |
| **Agents** | 11 | Create, edit, and manage support agents with roles and permissions |
| **Conversations** | 9 | Search, view, and analyze customer conversations |
| **Activity** | 8 | Daily and weekly summaries, trends, and operational metrics |
| **AI Analysis** | 7 | Sentiment analysis, conversation summaries, and AI-powered insights |
| **Advanced** | 6 | Webhooks, custom functions (function calling), and CRM endpoints |
| **Smart Follow-up** | 6 | AI-driven purchase intent detection and automated follow-up messages |
| **Tasks** | 6 | Customer tasks and reminders with assignments and due dates |
| **Integrations** | 5 | Shopify connection, external services, and third-party platforms |
| **Notifications** | 5 | System notifications management and preferences |
| **Calendar** | 4 | Events and scheduled appointments linked to customers |
| **Knowledge Base** | 3 | Upload and manage documents for AI-powered answers |
| **Account** | 3 | Account details, billing, and subscription information |
| **Referrals** | 3 | Referral program — generate links and track commissions |
| **Products** | 2 | Product search and query statistics |
| **Support** | 1 | Contact WAzion support |

---

## Getting Your API Key

1. **Sign up** at [wazion.com](https://www.wazion.com)
2. **Connect** your WhatsApp number by scanning the QR code
3. Go to **Settings** > **Developer** and copy your API key

Your API key is the same token used for the dashboard. It uniquely identifies your shop and its configuration.

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WAZION_API_KEY` | Yes | Your WAzion API key (from Settings > Developer) |
| `WAZION_API_URL` | No | Custom endpoint URL (default: `https://www.wazion.com/api/mcp/`). Use this for self-hosted instances. |

---

## Examples

Once connected, you can ask your AI assistant things like:

**Send a message:**
> "Send a WhatsApp message to +34612345678 saying: Your order has been shipped!"

**Check conversations:**
> "Show me my most recent conversations from today"

**Create an automation:**
> "Create a workflow that auto-replies with AI when a customer sends a message outside business hours"

**Run a campaign:**
> "Start a mass marketing campaign to my VIP list with the message: Exclusive 20% discount this weekend!"

**Analyze performance:**
> "Give me a summary of this week's activity — messages, response times, and sentiment"

---

## Confirmations

Actions that modify data (deleting workflows, removing agents, clearing lists, etc.) use a two-step confirmation flow:

1. The first call returns a warning describing what will happen
2. A second call with `confirm: true` executes the action

This prevents accidental destructive operations. Your AI client handles this automatically.

---

## Self-Hosted

WAzion can be self-hosted on your own infrastructure. If you're running a self-hosted instance, set the `WAZION_API_URL` environment variable to point to your server:

```bash
WAZION_API_URL=https://your-instance.example.com/api/mcp/
```

All tools work identically with self-hosted installations.

---

## Troubleshooting

### "Unauthorized" or 401 errors
- Verify your API key is correct (Settings > Developer in the dashboard)
- Make sure the `Authorization: Bearer` header is properly formatted
- Check that your account is active

### Connection timeout
- Ensure `https://www.wazion.com` is accessible from your network
- If behind a proxy, configure your HTTP client accordingly
- For stdio transport, check that Node.js >= 18 is installed

### Tools not showing up
- Confirm the MCP server is connected (check your client's MCP status)
- Restart your AI client after adding the configuration
- Verify the API key has not been rotated

### WhatsApp messages not sending
- Check that your WhatsApp session is connected (scan QR if needed)
- Verify you have sufficient credits in your account
- Ensure the phone number includes the country code (e.g., +34612345678)

---

## Links

- [WAzion Website](https://www.wazion.com)
- [API Documentation](https://www.wazion.com/en/help/dashboard/advanced/crm-endpoints/)
- [Developer Integration Guide](https://www.wazion.com/en/help/dashboard/advanced/developer-integration-guide/)
- [GitHub Issues](https://github.com/wazionapps/mcp-server/issues)

---

## License

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