Verdant Meta MCP

A Model Context Protocol (MCP) server for Meta's WhatsApp Business Management API, built with Node.js and TypeScript. It manages WhatsApp message templates directly against the Meta Graph API.

Features

Template Operations

• meta_list_templates - List templates in the WhatsApp Business Account (filter by name, status, category or language, with pagination)
• meta_get_template - Fetch a single template by its ID, including review status and rejected reason
• meta_create_template - Create a new template and submit it to Meta for review
• meta_edit_template - Edit an existing template and resubmit it for review
• meta_delete_template - Delete a template (all languages by name, or one language by ID)

Media Operations

• meta_upload_media - Upload a sample image (JPG, PNG), video (MP4) or document (PDF) from a local path or a public https URL, and get back the handle a media header needs. Local paths must end in one of those extensions

Analytics Operations

• meta_get_template_analytics - Sent, delivered, read and button click counts for up to 10 templates over a date range (UTC days, 90 days of history)

Meta's Rules on Edits and Deletes

• Only APPROVED, REJECTED or PAUSED templates can be edited
• An approved template can be edited once per 24 hours and up to 10 times per 30 days
• The category of an approved template cannot be changed
• An edit replaces the template's components in full and sends it back through review
• After deleting an approved template, its name cannot be reused for 30 days

meta_create_template, meta_edit_template and meta_delete_template change the live WhatsApp Business Account, and meta_upload_media reads a local file or downloads a URL and sends it to Meta. Auto-approve only the read tools: meta_list_templates, meta_get_template and meta_get_template_analytics.

Setup

Prerequisites

• Node.js 20 or higher
• A Meta Business account with a WhatsApp Business Account (WABA)

Getting Your Credentials

1. In Meta Business Settings, create a System User and generate an access token with the whatsapp_business_management permission, with the WABA assigned to it
2. Copy the WhatsApp Business Account ID from WhatsApp Manager (Account tools → Business account info), or from Business Settings → Accounts → WhatsApp Accounts

Installation

From Source

git clone https://github.com/Verdant-Solar/verdant-meta-mcp.git
cd verdant-meta-mcp
npm install
npm run build

Using npm (when published)

npm install -g verdant-meta-mcp

Configuration

Environment Variables

Set the following environment variables:

export META_ACCESS_TOKEN="your_meta_access_token"
export META_WABA_ID="your_whatsapp_business_account_id"

The Graph API version is pinned inside the server (currently v24.0) and is updated through a package release.

Or create a .env file (see .env.example):

cp .env.example .env
# Edit .env with your credentials

MCP Client Configuration

{
  "mcpServers": {
    "meta": {
      "command": "npx",
      "args": ["-y", "verdant-meta-mcp@latest"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token",
        "META_WABA_ID": "your_whatsapp_business_account_id"
      },
      "autoApprove": [
        "meta_list_templates",
        "meta_get_template",
        "meta_get_template_analytics"
      ]
    }
  }
}

Or from a local build:

{
  "mcpServers": {
    "meta": {
      "command": "node",
      "args": ["/path/to/verdant-meta-mcp/build/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token",
        "META_WABA_ID": "your_whatsapp_business_account_id"
      }
    }
  }
}

Usage

Running the Server

node build/index.js

Using with MCP Inspector

For debugging and testing:

npm run inspector

The Inspector will provide a URL you can open in your browser to interact with the server.

Development

Watch Mode

For development with auto-rebuild:

npm run watch

Building

npm run build

Docker

Build and run with Docker:

docker build -t verdant-meta-mcp .
docker run -i --rm \
  -e META_ACCESS_TOKEN="your_access_token" \
  -e META_WABA_ID="your_waba_id" \
  verdant-meta-mcp

Releasing

Pushing to the production branch publishes the package to npm. Bump version in package.json first, because npm rejects a version that is already published.

Example Usage

Once configured with an MCP client, you can:

• "List all approved WhatsApp templates"
• "Show me the rejected templates and why they were rejected"
• "Get template 1234567890"
• "Change the body text of template 1234567890 and resubmit it"
• "Create a utility template called order_update in English"
• "Upload /path/to/banner.png and use it as the header of a new marketing template"
• "How many times was template 1234567890 sent and read in the last 30 days?"

Components Format

meta_create_template and meta_edit_template take components in Meta Graph API format:

[
  { "type": "HEADER", "format": "TEXT", "text": "Order update" },
  {
    "type": "BODY",
    "text": "Hi {{1}}, your order {{2}} is on the way.",
    "example": { "body_text": [["Aina", "VS-1024"]] }
  },
  { "type": "FOOTER", "text": "Verdant Solar" },
  {
    "type": "BUTTONS",
    "buttons": [{ "type": "QUICK_REPLY", "text": "Track order" }]
  }
]

Media Headers

A template with an IMAGE, VIDEO or DOCUMENT header needs a sample file. Call meta_upload_media first, then pass the returned handle in the header:

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": { "header_handle": ["<handle from meta_upload_media>"] }
}

The upload goes to the Meta app that issued the access token, so no extra configuration is needed.

Analytics

meta_get_template_analytics needs template insights enabled on the WhatsApp Business Account (WhatsApp Manager → Insights). startDate and endDate are inclusive UTC days; without them it reports the last 7 full days.

Troubleshooting

Authentication Issues

• Verify your META_ACCESS_TOKEN is correct and has not expired
• Check that the token has the whatsapp_business_management permission
• Check that the System User is assigned to the WABA in META_WABA_ID

Template Rejected or Edit Refused

• The error text returned by the tool includes Meta's own reason
• Use meta_get_template to read status and rejected_reason
• Check the edit limits listed above

License

MIT