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

# Setup & Configuration

> Install and configure the Zeplo MCP Server for use with Claude Code, Cursor, and other MCP-compatible AI assistants.

# Setup & Configuration

## Install & Build

**1. Install dependencies**

```bash theme={null}
cd packages/zeplo-mcp-server
npm install
```

**2. Build the server**

```bash theme={null}
npm run build
```

This compiles TypeScript to `dist/index.js` — the entry point your MCP client will run.

**3. Set environment variables**

Create a `.env` file in the `zeplo-mcp-server` directory (or set them in your client config):

```env theme={null}
DATABASE_URL=postgresql://user:password@localhost:5432/whatsapp
```

The server needs read/write access to the same PostgreSQL database used by your Zeplo instance.

## Configure Your Client

**Claude Code (CLI)**

Add to your project's `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "zeplo": {
      "command": "node",
      "args": ["/absolute/path/to/wa-automation/packages/zeplo-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/whatsapp"
      }
    }
  }
}
```

Or via the CLI:

```bash theme={null}
claude mcp add zeplo \
  -e DATABASE_URL=postgresql://user:pass@localhost:5432/whatsapp \
  -- node /path/to/wa-automation/packages/zeplo-mcp-server/dist/index.js
```

**Cursor**

Add to your `~/.cursor/mcp.json` or project `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "zeplo": {
      "command": "node",
      "args": ["/absolute/path/to/wa-automation/packages/zeplo-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/whatsapp"
      }
    }
  }
}
```

**Windsurf**

Add to your Windsurf MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "zeplo": {
      "command": "node",
      "args": ["/absolute/path/to/wa-automation/packages/zeplo-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/whatsapp"
      }
    }
  }
}
```

**VS Code (Copilot)**

Add to your VS Code `settings.json`:

```json theme={null}
{
  "mcp.servers": {
    "zeplo": {
      "command": "node",
      "args": ["/absolute/path/to/wa-automation/packages/zeplo-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/whatsapp"
      }
    }
  }
}
```

## Verify It Works

Restart your AI assistant, then ask it to check system health:

```
Check the Zeplo system health
```

If configured correctly, the assistant will call the `system_health` tool and report the database connection status.

## Environment Variables

| Variable | Required | Description |
| - | - | - |
| `DATABASE_URL` | Yes | PostgreSQL connection string for your Zeplo database |

## Development

For local development without building each time:

```bash theme={null}
npm run dev    # Run with tsx (no build step)
npm run build  # Build for production
npm start      # Run the compiled version
```

> [!NOTE]
>
> The MCP server communicates over **stdio** — it reads from stdin and writes to stdout. Logs and errors go to stderr. Your MCP client handles the transport automatically.

## Dry-Run Mode

Tools that create or modify data (`contact_create`, `campaign_create`, `message_send_text`, `message_send_template`, `chatbot_train`) support a `dryRun` parameter. Set `dryRun: true` to validate inputs without writing to the database.

## Error Handling

The server returns structured errors for:

* **Not found** — resource with the given ID doesn't exist
* **Validation failed** — input doesn't match the expected schema
* **Database error** — connection issues or constraint violations
* **Automation not active** — attempting to execute a paused or inactive automation

All errors include a descriptive message explaining what went wrong.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.