Connect Claude to MoltFlow via MCP Server

Claude Desktop gains superpowers when you install the MoltFlow MCP server. One config file gives Claude direct access to your WhatsApp API — 25 tools across sessions, messages, leads, groups, outreach, and usage. Setup takes 5 minutes.

Unlike Custom GPT Actions (which require manual OpenAPI imports), MCP (Model Context Protocol) provides Claude with native tool discovery, streaming responses, and stateful context. Claude doesn't just call your API — it understands your WhatsApp automation platform as if it were built-in functionality.

This guide covers three connection methods: Claude Desktop (local), Claude.ai web (remote), and Claude Code (CLI). Choose the method that fits your workflow.

What You'll Need

Before starting, make sure you have:

• A MoltFlow account — API keys are available on all plans (Free, Growth, Business). Sign up here if you don't have an account yet.
• A MoltFlow API key — Create one at Dashboard > Settings > API Keys.
• One of these clients:
  • Claude Desktop app — Download from claude.ai/download (macOS, Windows, Linux)
  • Claude.ai web account — No installation needed, use the remote gateway
  • Claude Code CLI — For developers using Claude in the terminal

For Claude Desktop or Claude Code: You'll also need Node.js 18+ installed. Check your version:

node --version

If you see v18.0.0 or higher, you're ready. If not, download Node.js from nodejs.org.

Claude.ai web users don't need Node.js — the remote MCP gateway runs on MoltFlow's servers.

Why Claude + MoltFlow?

MCP turns Claude into a first-class WhatsApp automation client. Instead of copying data between dashboards, Claude accesses your MoltFlow account directly:

• Native tool execution — Claude calls MoltFlow APIs as if they were built-in commands
• Streaming responses — See session status, message counts, and lead details in real-time as Claude fetches them
• Context-aware workflows — Claude remembers your sessions, groups, and campaigns across your conversation
• Multi-step operations — Complex workflows like "create group, add contacts, send bulk message" handled in one request

Example use cases:

• Ask Claude "How many messages did I send this week?" and get usage analytics instantly
• Say "Send a follow-up to all leads from the NYC Events group" and Claude executes the full workflow
• Request "Show me sessions that need QR code renewal" and Claude filters by status automatically
• Command "Create a bulk send to my Newsletter group with [message]" and Claude confirms before executing

Step 1: Prerequisites and API Key Setup

First, create a MoltFlow API key with the scopes your MCP tools need.

Create your API key:

1. Log in to MoltFlow Dashboard
2. Navigate to Settings in the left sidebar
3. Click API Keys
4. Click "Create API Key"
5. Give it a descriptive name: Claude MCP Server
6. Choose your scopes:

For full MCP functionality, select these scopes:

• sessions:read — List sessions, get QR codes, check status
• sessions:manage — Create and start sessions
• messages:send — Send WhatsApp messages via Claude commands
• messages:read — View chat history and message logs
• messages:write — Create bulk send campaigns and scheduled messages
• groups:read — List monitored groups and available groups
• groups:manage — Add groups to lead monitoring
• custom-groups:read — List custom contact groups
• custom-groups:manage — Create and edit groups, add members
• leads:read — Query leads from monitored groups
• leads:write — Update lead status and pipeline stages
• usage:read — Check message limits and plan usage

Select the scopes that match the tools you plan to use (see the scope table above).

1. Click Create
2. Copy the API key immediately — it's only shown once

Store the key securely. You'll add it to your MCP configuration in the next step.

Step 2: Set Up MCP Server for Claude Desktop

This is the primary method — local MCP server via Claude Desktop's native integration.

Claude Desktop supports MCP servers through a simple JSON configuration file. We'll add the MoltFlow MCP server using npx (no installation required).

Locate your config file:

The Claude Desktop config file location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Create or edit the config file:

If the file doesn't exist, create it. If it exists, add the moltflow server to the mcpServers object.

Option A: Via npx (no install needed) — Recommended

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "moltflow": {
      "command": "npx",
      "args": ["-y", "@moltflow/mcp-server"],
      "env": {
        "MOLTFLOW_API_KEY": "mf_your_api_key_here"
      }
    }
  }
}

Replace mf_your_api_key_here with your actual MoltFlow API key from Step 1.

The -y flag tells npx to auto-confirm package installation. @moltflow/mcp-server is fetched from npm and executed directly — no global install needed.

Option B: Global install

If you prefer a persistent installation:

npm install -g @moltflow/mcp-server

Then use this config:

{
  "mcpServers": {
    "moltflow": {
      "command": "moltflow-mcp-server",
      "env": {
        "MOLTFLOW_API_KEY": "mf_your_api_key_here"
      }
    }
  }
}

The globally installed moltflow-mcp-server command is now available system-wide.

Important for existing configs:

If your claude_desktop_config.json already has other MCP servers, just add moltflow to the mcpServers object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    },
    "moltflow": {
      "command": "npx",
      "args": ["-y", "@moltflow/mcp-server"],
      "env": {
        "MOLTFLOW_API_KEY": "mf_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop:

After saving the config file:

1. Quit Claude Desktop completely (not just close the window)
2. Reopen Claude Desktop
3. Look for a hammer icon in the chat input area

The hammer icon indicates MCP tools are loaded. Hover over it to see the list of connected servers — moltflow should appear.

If you don't see the hammer icon, check the Claude Desktop logs for errors. Common issues: invalid JSON syntax, wrong file path, or Node.js not installed.

Step 3: Connect via Claude.ai Web (Remote Gateway)

Claude.ai web users can connect to MoltFlow without any local installation using the remote MCP gateway.

Configure MCP in Claude.ai:

1. Log in to Claude.ai
2. Click your profile icon in the bottom-left
3. Select Settings
4. Navigate to Integrations tab
5. Find MCP Servers section
6. Click "Add Server"

Enter connection details:

• Server Name: MoltFlow
• URL: https://apiv2.waiflow.app/mcp
• Authentication: Custom Header
• Header Name: X-API-Key
• Header Value: Your MoltFlow API key

1. Click Save

Claude.ai will test the connection. If successful, you'll see "MoltFlow" appear in your connected servers list.

How the remote gateway works:

The MoltFlow API hosts an HTTP MCP gateway at /mcp. When you send commands from Claude.ai, requests go to MoltFlow's servers, which execute the API calls and return responses to Claude. Your API key authenticates each request.

Advantages of the remote gateway:

• No local software installation required
• Works on any device with web browser access
• No Node.js or npm dependencies
• Updates automatically (no manual package updates)

Security note:

The remote gateway uses HTTPS with API key authentication. Rate limits apply (120 requests/minute per API key). For higher throughput or stricter security requirements, use Claude Desktop with local MCP server instead.

Step 4: Set Up Claude Code with the MoltFlow Plugin

Claude Code users can access MoltFlow via the official plugin directory.

The plugin provides two features:

1. Guided skills — 5 slash commands for common operations (/moltflow:send-message, /moltflow:list-sessions, /moltflow:check-leads, /moltflow:bulk-send, /moltflow:help)
2. MCP tools — All 25 tools accessible conversationally (same as Claude Desktop)

Set up the plugin:

1. Clone or download the MoltFlow repository (or just the moltflow-plugin/ directory)
2. Set your API key as an environment variable:

# macOS/Linux
export MOLTFLOW_API_KEY=mf_your_api_key_here

# Windows (PowerShell)
$env:MOLTFLOW_API_KEY = "mf_your_api_key_here"

1. Launch Claude Code with the plugin directory:

claude --plugin-dir ./moltflow-plugin

Replace ./moltflow-plugin with the actual path to the plugin directory.

Using guided skills:

Type /moltflow: and tab-complete to see available skills:

• /moltflow:send-message — Guided flow for sending WhatsApp messages
• /moltflow:list-sessions — View all sessions with status
• /moltflow:check-leads — Query leads by status or date range
• /moltflow:bulk-send — Create and monitor bulk messaging campaigns
• /moltflow:help — Full command reference

Using MCP tools conversationally:

After launching with the plugin, you can use MCP tools naturally:

"List my WhatsApp sessions"
"Send a message to +1-555-0123 saying hello"
"Show me new leads from this week"

Claude Code will execute the appropriate MCP tool calls automatically.

Step 5: Test MCP Tools with Sample Commands

Now that you've connected Claude to MoltFlow, let's test the integration.

Open a chat and try these commands:

1. List sessions:

"List my WhatsApp sessions"

Expected response: A formatted markdown table showing your sessions with columns for Name, Status (working/stopped/qr_code), Phone Number, and Session ID.

If you have no sessions, Claude will tell you how to create one.

2. Check usage:

"What's my current message usage?"

Expected response: Current billing period stats — messages sent, messages remaining, plan limits, and reset date. This confirms Claude can read your account data.

3. View leads:

"Show me new leads from this week"

Expected response: A list of leads captured in the last 7 days with status "new". Claude will format the results with contact name, phone, lead score, source group, and capture date.

4. Send a test message:

"Send a message to +1-555-0123 saying Hello from Claude via MCP!"

Replace +1-555-0123 with your own phone number. Claude will ask you to select a session if you have multiple, then send the message.

Check your phone — you should receive the message within seconds.

5. List available groups:

"What WhatsApp groups can I monitor for leads?"

Expected response: A list of groups from your connected sessions with group name, participant count, and whether they're already being monitored.

What to look for:

• Responses should be formatted in markdown (tables, bold text, lists) — not raw JSON
• Tool execution should happen automatically — Claude chooses the right MCP tool without you specifying it
• Claude should ask clarifying questions if needed (e.g., "Which session do you want to use?")
• Error messages should be actionable (e.g., "Session xyz-123 is stopped. Start it first.")

Test complex workflows:

Try multi-step commands:

"Create a custom group called 'Test Group', add +1-555-0001 and +1-555-0002 to it, then send them a bulk message saying 'Testing bulk send'"

Claude will execute multiple MCP tools in sequence:

1. moltflow_create_custom_group — Creates the group
2. moltflow_add_custom_group_members — Adds the contacts
3. moltflow_create_bulk_send — Sends the message

This demonstrates the power of MCP — Claude orchestrates multi-step workflows from a single request.

Step 6: Explore Available Tools and Customization

The MoltFlow MCP server provides 25 tools across 6 domains.

Sessions (5 tools)

Messages (3 tools)

Groups (6 tools)

Leads (2 tools)

Outreach (4 tools)

Usage (2 tools)

Response formats:

All tools support two response formats:

• markdown (default) — Human-readable formatted output with tables, lists, and bold text. Best for conversational use in Claude.
• json — Raw JSON response from the MoltFlow API. Best for programmatic processing or when you need exact field values.

To request JSON format, ask explicitly:

"List my sessions in JSON format"

Pagination:

List tools support limit and offset parameters for paginating through large result sets:

"Show me the first 10 leads"          -> limit: 10, offset: 0
"Show me the next 10 leads"           -> limit: 10, offset: 10
"Show me leads 21-30"                 -> limit: 10, offset: 20

When more results are available, Claude will indicate how to fetch the next page.

Environment variables:

You can customize the MCP server behavior with these environment variables in your config:

Add them to the env section of your config:

{
  "mcpServers": {
    "moltflow": {
      "command": "npx",
      "args": ["-y", "@moltflow/mcp-server"],
      "env": {
        "MOLTFLOW_API_KEY": "mf_your_api_key_here",
        "MOLTFLOW_API_URL": "https://your-custom-domain.com/api/v2"
      }
    }
  }
}

Self-Hosted HTTP Gateway (Advanced)

For advanced users, you can run the MCP server in HTTP mode and connect to it from custom clients.

Start the HTTP gateway:

TRANSPORT=http \
MOLTFLOW_API_KEY=mf_xxxxx \
PORT=3000 \
HOST=127.0.0.1 \
npx @moltflow/mcp-server

Configuration:

Endpoints:

• POST /mcp — MCP protocol endpoint (requires X-API-Key header)
• GET /health — Health check

Production deployment:

Run behind a reverse proxy (Nginx, Caddy) for HTTPS termination:

location /mcp {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header Host $host;
}

This is useful if you're deploying MoltFlow integrations for a team and want centralized MCP gateway management.

Troubleshooting

"MOLTFLOW_API_KEY environment variable is not set"

Cause: The MCP server starts but all tool calls fail with authentication errors.

Fix:

Check your claude_desktop_config.json has the env.MOLTFLOW_API_KEY field set correctly:

{
  "mcpServers": {
    "moltflow": {
      "command": "npx",
      "args": ["-y", "@moltflow/mcp-server"],
      "env": {
        "MOLTFLOW_API_KEY": "mf_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after fixing.

Tools Not Appearing in Claude Desktop

Cause: Claude Desktop doesn't see the MCP server.

Possible issues:

1. Config file is not valid JSON (trailing commas, missing quotes)
2. Config file is in the wrong location for your OS
3. Node.js is not installed or not in PATH
4. Claude Desktop wasn't fully restarted

Fix:

1. Validate JSON: Use jsonlint.com to check syntax
2. Verify file location (see Step 2 for OS-specific paths)
3. Test Node.js: Run node --version in terminal
4. Restart Claude Desktop: Quit completely (not just close window), then reopen
5. Check Claude Desktop logs for MCP server errors

"401 Unauthorized" on every tool call

Cause: API key is invalid or expired.

Fix:

1. Verify your API key is still active at Settings > API Keys
2. Regenerate a new key if needed
3. Update claude_desktop_config.json with the new key
4. Restart Claude Desktop

"403 Forbidden -- insufficient scope"

Cause: Your API key doesn't have the required scope for the tool you're trying to use.

Fix:

1. Create a new API key with the required scopes for the tools you need
2. Update your config with the new key
3. Restart Claude Desktop

"429 Rate Limited"

Cause: Too many requests in a short time.

Fix:

Wait for the retry period. Rate limits by plan:

• Free: 10 requests/min
• Starter: 20 requests/min
• Growth: 40 requests/min
• Business: 60 requests/min

For higher limits, upgrade your plan.

Session Stuck in "starting" State

Cause: The WAHA engine needs time to initialize.

Fix:

Wait 10-15 seconds, then ask Claude "What's the status of session [ID]?" to check progress. If it stays "starting" for more than 30 seconds, restart the session from the MoltFlow dashboard.

QR Code Expired

Cause: QR codes expire after approximately 60 seconds.

Fix:

Ask Claude "Get a fresh QR code for session [ID]" to generate a new one.

HTTP Gateway Not Responding

Cause: Server not running or port conflict.

Possible issues:

1. TRANSPORT=http environment variable not set
2. Port already in use by another process
3. Firewall blocking the port

Fix:

1. Verify TRANSPORT=http is set when launching
2. Check port availability: lsof -i :3000 (macOS/Linux) or netstat -ano | findstr 3000 (Windows)
3. Use a different port: PORT=3001 npx @moltflow/mcp-server

What's Next

Now that you've connected Claude to MoltFlow, explore these related integrations:

• Connect ChatGPT to MoltFlow via Custom GPT Actions — Give ChatGPT Plus full WhatsApp automation access with OpenAPI spec import
• Connect OpenClaw Bot to MoltFlow — Native AI integration for automatic WhatsApp replies
• Build a WhatsApp Support Bot — Combine AI with knowledge base for 24/7 customer service
• Connect MoltFlow to n8n — Integrate WhatsApp with 500+ apps via no-code workflows

Claude + MoltFlow via MCP turns natural language into WhatsApp automation. Use it for ad-hoc operations, team collaboration, or as a conversational alternative to the dashboard.

Ready to build more integrations? Check out MoltFlow's full REST API documentation for advanced workflows.

Need help? Contact support via the dashboard chat or email us at [email protected]. We typically respond within 2-4 hours.