Content
# manychat-mcp
A [Model Context Protocol](https://modelcontextprotocol.io) server that wraps
the **ManyChat Account/Page API** so Claude (or any MCP client) can manage
subscribers, tags, custom fields, and trigger flows / send content.
18 tools across six capability areas — page, subscribers, tags, custom fields,
bot fields, and sending.
## Quick install
```bash
pip install manychat-mcp
```
Or with `uv`:
```bash
uv tool install manychat-mcp
```
## Setup
### 1. Generate a ManyChat API key
In ManyChat → **Settings → API → Generate your API key**. The key is scoped
to a single page/account. Copy it.
See ManyChat's guide:
https://help.manychat.com/hc/en-us/articles/14959510331420
### 2. Configure `.env`
```bash
MANYCHAT_API_KEY=YOUR_PAGE_API_KEY
```
Optional overrides:
```bash
# Default: https://api.manychat.com
MANYCHAT_API_BASE=https://api.manychat.com
# Path prefix; ManyChat uses /fb/ for the unified account API. Override
# only if ManyChat changes this.
MANYCHAT_API_PREFIX=fb
```
## Connect to Claude Desktop
Edit `~/.config/Claude/claude_desktop_config.json` (Linux) /
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"manychat": {
"command": "manychat-mcp",
"env": {
"MANYCHAT_API_KEY": "YOUR_PAGE_API_KEY"
}
}
}
}
```
Restart Claude Desktop. You should see 18 tools under the `manychat` server.
## Available tools
### Page
| Tool | What it does |
|---|---|
| `get_page_info` | Page / account info this key is scoped to. |
| `list_tags` | All tags on the page (id + name). |
| `create_tag` | Create a new tag. |
| `list_custom_fields` | Subscriber-level custom fields. |
| `list_bot_fields` | Page-level (bot) fields. |
| `list_flows` | All flows ('automations') with their `ns` IDs. |
### Subscribers
| Tool | What it does |
|---|---|
| `get_subscriber` | Look up by `subscriber_id`. |
| `get_subscriber_by_user_ref` | Look up by `user_ref`. |
| `find_subscriber_by_name` | Search by name. |
| `find_subscriber_by_custom_field` | Search by a custom field value. |
### Tags
| Tool | What it does |
|---|---|
| `add_tag` | Add a tag (by name) to a subscriber. |
| `remove_tag` | Remove a tag (by name) from a subscriber. |
### Custom fields
| Tool | What it does |
|---|---|
| `set_custom_field` | Set one field by name. |
| `set_custom_fields` | Set multiple fields by ID in one call. |
### Bot (page-level) fields
| Tool | What it does |
|---|---|
| `set_bot_field` | Set a page-level field by name. |
### Sending
| Tool | What it does |
|---|---|
| `send_content` | Send a content block to a subscriber. Optional `message_tag` for outside the 24h window. |
| `send_content_by_user_ref` | Same, addressed by `user_ref`. |
| `send_flow` | Trigger a flow (automation) for a subscriber. |
## Notes & gotchas
- **API prefix is `/fb/` even for Instagram/WhatsApp pages.** ManyChat's
account API is unified — the channel is determined by how the page is
configured inside ManyChat, not by the URL path.
- **`send_content` outside 24h needs a `message_tag`.** Same rule as Meta's
Messenger Platform — without a tag you can only message a subscriber inside
the 24h user-initiated window. Tags require Meta approval.
- **Errors return a structured dict**, not exceptions. Look for `error: true`
with `status`, `message`, and `details`.
- **`flow_ns`** is the flow namespace (looks like `content_xxxxxxxx`); get
these from `list_flows()`.
## Development
```bash
git clone https://github.com/AleemHaider/manychat-mcp
cd manychat-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```
## License
MIT — see [LICENSE](LICENSE).
