Setup & Configuration

Install & Build

Install dependencies

cd packages/zeplo-mcp-server
npm install

Build the server

npm run build

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

Set environment variables

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

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)
Cursor
Windsurf
VS Code (Copilot)

Add to your project’s .claude/settings.json:

{
  "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:

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

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

{
  "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"
      }
    }
  }
}

Add to your Windsurf MCP configuration:

{
  "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"
      }
    }
  }
}

Add to your VS Code settings.json:

{
  "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:

npm run dev    # Run with tsx (no build step)
npm run build  # Build for production
npm start      # Run the compiled version

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.

Getting Started

Tools Reference

Resources

Setup & Configuration

Setup & Configuration

Install & Build

Configure Your Client

Verify It Works

Environment Variables

Development

Dry-Run Mode

Error Handling

​Setup & Configuration

​Install & Build

​Configure Your Client

​Verify It Works

​Environment Variables

​Development

​Dry-Run Mode

​Error Handling

Setup & Configuration

Install & Build

Configure Your Client

Verify It Works

Environment Variables

Development

Dry-Run Mode

Error Handling