Meta Business Mcp

by metabusiness-mcp

1 438 downloads Not rated yet

GitHub Website

Communication

About

Production-validated MCP server for WhatsApp Business Cloud API — compliance engine, error intelligence & message orchestration for AI agents. 24 tools, sub-2ms decisions, 85.6% test coverage.

Explore

- 24 structured MCP tools for AI Agents
- Compliance gate evaluating every outbound message
- Async message delivery via NATS JetStream with retries
- Per‑customer rate limiting via Redis token bucket
- Error intelligence translating Meta API error codes
- Campaign management with scheduling and audience filters
- Template lifecycle management with Meta API sync

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Meta Business Mcp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

From the repository

Place config.yaml in the project root for local development:

server: http_port: 8080 mcp_name: "meta-business-mcp" mcp_version: "1.0.0" database: host: "localhost" port: 5432 user: "postgres" password: "password" dbname: "meta_mcp" sslmode: "disable" redis: addr: "localhost:6379" nats: url: "nats://localhost:4222" meta: api_url: "http://localhost:8081" # Use mock server for offline dev phone_number_id: "mock-phone-id" waba_id: "mock-waba-id" access_token: "mock-access-token" webhook_verify_token: "mock-verify-token"

policies_path: "policies.yaml" tier: "oss" # oss | pro | enterprise

All config values can be overridden with environment variables. Required values are marked with ✅.

| Variable | Default | Required | Description |
|---|---|---|---|
| SERVER_HTTP_PORT | 8080 | — | HTTP server port |
| SERVER_MCP_NAME | "meta-business-mcp" | — | MCP server identifier |
| SERVER_MCP_VERSION | "1.0.0" | — | MCP server version string |
| DB_HOST | "localhost" | — | PostgreSQL host |
| DB_PORT | 5432 | — | PostgreSQL port |
| DB_USER | "postgres" | — | PostgreSQL username |
| DB_PASSWORD | "password" | — | PostgreSQL password |
| DB_NAME | "meta_mcp" | — | PostgreSQL database name |
| DB_SSLMODE | "disable" | — | disable, require, or verify-ca |
| REDIS_ADDR | "localhost:6379" | — | Redis connection address |
| REDIS_PASSWORD | "" | — | Redis auth password |
| REDIS_DB | 0 | — | Redis database index |
| NATS_URL | "nats://localhost:4222" | — | NATS connection URL |
| META_API_URL | "https://graph.facebook.com" | — | Meta Graph API base URL |
| META_ACCESS_TOKEN | — | ✅ | Meta API OAuth token (system user) |
| META_PHONE_NUMBER_ID | — | ✅ | WhatsApp Business Phone Number ID |
| META_WABA_ID | — | ✅ | WhatsApp Business Account ID |
| META_WEBHOOK_VERIFY_TOKEN | — | ✅ | Meta webhook verification passphrase |
| POLICIES_PATH | "policies.yaml" | — | Path to the business policy seed YAML file |
| TIER | "oss" | — | Feature tier: oss, pro, or enterprise |
| SCHEDULER_POLL_INTERVAL | "30s" | — | Scheduler polling interval for scheduled messages/campaigns |

SERVER_HTTP_PORT=8080
SERVER_MCP_NAME=meta-business-mcp
SERVER_MCP_VERSION=1.0.0
TIER=oss
DB_HOST=postgres.prod.internal

DB_PORT=5432

DB_USER=mcp_user

DB_PASSWORD=production_secure_postgres_pass

DB_NAME=meta_mcp

DB_SSLMODE=require
REDIS_ADDR=redis.prod.internal:6379

REDIS_PASSWORD=production_redis_auth_pass

REDIS_DB=0
NATS_URL=nats://nats.prod.internal:4222
META_API_URL=https://graph.facebook.com

META_ACCESS_TOKEN=EAAG...production_long_lived_system_user_token...

META_PHONE_NUMBER_ID=106555123456789

META_WABA_ID=204555123456789

META_WEBHOOK_VERIFY_TOKEN=production_webhook_verification_passphrase
POLICIES_PATH=/app/policies.yaml

SCHEDULER_POLL_INTERVAL=30s

All 24 tools are exposed to AI Agents over stdio using the Model Context Protocol. All tools are production-ready and validated against real WABA production (Meta Graph API v20.0).

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "meta business mcp": {
            "meta-business-mcp": {
                "command": "/path/to/meta-business-mcp",
                "args": [],
                "env": {
                    "CONFIG_PATH": "/path/to/config.yaml"
                }
            }
        }
    }
}

McpServers

{
    "meta-business-mcp": {
        "command": "/path/to/meta-business-mcp",
        "args": [],
        "env": {
            "CONFIG_PATH": "/path/to/config.yaml"
        }
    }
}

Go 1.21+ License: Apache 2.0 Tests: Passing Coverage: 85.6% Tools: 24 Production-Validated

> A WhatsApp compliance intelligence platform that ensures every AI Agent can operate WhatsApp Business safely, compliantly, and production-ready — without understanding Meta's rule complexity.

For: AI Agent developers · Digital agencies · WhatsApp automation teams
21 tools free forever · 3 campaign tools on Pro

---

1. Why This Exists
2. What It Does
3. Quick Start
4. MCP Tools
5. Architecture
6. Configuration
7. Testing
8. Deployment
9. Business Model
10. Roadmap
11. Observability
12. Documentation Index
13. Contributing
14. License

---

Why This Exists

AI Agents don't understand Meta's WhatsApp Business rules — 24-hour care windows, frequency caps, template categories, opt-out mandates, rate limits. Sending a single message wrong means account suspension, message rejection, and compliance violations. Meta Business MCP sits between the AI Agent and Meta's API, enforcing every rule automatically so the Agent never has to learn them.

---

What It Does

| Responsibility | Description |
|---|---|
| Compliance Gate | Evaluates every outbound message against Meta's care window rules, opt-out lists, and frequency caps before delivery. |
| Policy Enforcement | Applies custom business policies (time boundaries, segment exclusions, VIP tag overrides) from a YAML-seeded database. |
| Async Message Delivery | Queues messages to NATS JetStream and dispatches them via a worker pool with automatic retries and exponential backoff. |
| Rate Limiting | Enforces per-customer token-bucket rate limits via Redis Lua scripts. |
| Error Intelligence | Translates numeric Meta API error codes into categorized, actionable developer instructions. |
| Campaign Management | Schedule, pause, cancel campaigns with audience segmentation and template validation. |
| Template Lifecycle | Create, sync, and validate templates via Meta API with local persistence. |
| MCP Server | Exposes 24 structured tools to AI Agents over stdio using the Model Context Protocol. |
| Webhook Receiver | Processes inbound events from Meta: customer messages, delivery status updates, and template approval callbacks. |

---

Quick Start

1. Clone and Start

git clone https://github.com/metabusiness-mcp/meta-business-mcp.git
cd meta-business-mcp
docker compose up -d --build

Wait for all containers to become healthy:

```bash
docker compose ps

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Explore

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Table of Contents

Why This Exists

What It Does

Quick Start

1. Clone and Start

More like this

Slack

Inbox Zero

Production-ready MCP integrations for AI applications

whatsapp-mcp