# Bento MCP Server

Connect your favorite AI assistant to Bento and manage your email marketing with natural language.

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants like Claude, Cursor, and others interact with external tools and services. The Bento MCP server gives your AI assistant direct access to your Bento account—look up subscribers, create broadcasts, track events, and more, all through natural conversation.

Whether you're drafting a campaign, importing subscribers, or checking your stats, just ask your AI assistant and it handles the rest.

---


> **Before you begin, make sure you have:**
> - A Bento account with API access
> - Your Bento API credentials (Publishable Key, Secret Key, Site UUID)
> - An AI application that supports MCP (Claude Desktop, Cursor, VS Code, etc.)
> - Node.js 18 or later installed on your machine


---


## Getting Your API Credentials


**1. Navigate to Settings**


Log into your Bento account and click on **Settings** in the left sidebar.


**2. Access API Keys**


Go to [Team Settings](https://app.bentonow.com/account/teams) and find your API keys.


**3. Copy Your Credentials**


You'll need three values:

| Credential | Description | Example |
|------------|-------------|---------|
| **Publishable Key** | Your public API key | `pk_live_abc123...` |
| **Secret Key** | Your private API key (keep this safe!) | `sk_live_xyz789...` |
| **Site UUID** | Your unique site identifier | `site_uuid_here` |


> If you don't see API keys, click "Generate Key" to create a new set.


> 🚨 **Important**
> Keep your Secret Key private! Never commit it to version control or share it publicly. Anyone with your secret key has full API access to your Bento account.


---


## Installation


```bash
npm install -g @bentonow/bento-mcp
```

---


## Setup Guides by Platform


Choose your AI application below for step-by-step setup instructions.


  
    
      <div className="flex items-center gap-3">
        
        <span>Claude Desktop</span>
      </div>
    
    
      <p className="mb-4">Claude Desktop is Anthropic's official desktop application with built-in MCP support.</p>

      <h4 className="font-semibold text-white mb-2">macOS Configuration</h4>
      <p className="mb-2">Open your configuration file:</p>
      <pre className="bg-zinc-900 rounded px-3 py-2 text-xs mb-3 overflow-x-auto">~/Library/Application Support/Claude/claude_desktop_config.json</pre>

      <h4 className="font-semibold text-white mb-2">Windows Configuration</h4>
      <pre className="bg-zinc-900 rounded px-3 py-2 text-xs mb-3 overflow-x-auto">%APPDATA%\Claude\claude_desktop_config.json</pre>

      <p className="mb-2">Add the Bento MCP server:</p>
      
        <Code language="json" code={`{
  "mcpServers": {
    "bento": {
      "command": "npx",
      "args": ["-y", "@bentonow/bento-mcp"],
      "env": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  }
}`} />
      
      <p className="mt-3">Restart Claude Desktop. Look for the MCP tools icon (hammer) to verify the connection.</p>
    
  

  
    
      <div className="flex items-center gap-3">
        
        <span>Claude Code (Terminal/CLI)</span>
      </div>
    
    
      <p className="mb-4">Claude Code is Anthropic's command-line AI coding assistant.</p>

      <p className="mb-2">Open or create your settings file:</p>
      <pre className="bg-zinc-900 rounded px-3 py-2 text-xs mb-3 overflow-x-auto">~/.claude/settings.json</pre>

      <p className="mb-2">Add the MCP server configuration:</p>
      
        <Code language="json" code={`{
  "mcpServers": {
    "bento": {
      "command": "npx",
      "args": ["-y", "@bentonow/bento-mcp"],
      "env": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  }
}`} />
      
      <p className="mt-3">Restart Claude Code or run <code>/mcp</code> to reload servers.</p>
    
  

  
    
      <div className="flex items-center gap-3">
        
        <span>Cursor</span>
      </div>
    
    
      <p className="mb-4">Cursor is an AI-powered code editor with MCP support.</p>

      <ol className="list-decimal list-inside space-y-2 mb-3">
        <li>Open Cursor Settings → MCP</li>
        <li>Click "Add Server" or edit the configuration directly</li>
        <li>Add the configuration below</li>
        <li>Restart Cursor</li>
      </ol>

      
        <Code language="json" code={`{
  "mcpServers": {
    "bento": {
      "command": "npx",
      "args": ["-y", "@bentonow/bento-mcp"],
      "env": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  }
}`} />
      
    
  

  
    
      <div className="flex items-center gap-3">
        
        <span>VS Code with Continue</span>
      </div>
    
    
      <p className="mb-4">Continue is an open-source AI coding assistant for VS Code and JetBrains.</p>

      <p className="mb-2">Open Continue settings:</p>
      <pre className="bg-zinc-900 rounded px-3 py-2 text-xs mb-3 overflow-x-auto">~/.continue/config.json</pre>

      <p className="mb-2">Add under the <code>mcpServers</code> section:</p>
      
        <Code language="json" code={`{
  "mcpServers": [
    {
      "name": "bento",
      "command": "npx",
      "args": ["-y", "@bentonow/bento-mcp"],
      "env": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  ]
}`} />
      
      <p className="mt-3">Reload VS Code to apply changes.</p>
    
  

  
    
      <div className="flex items-center gap-3">
        
        <span>Windsurf</span>
      </div>
    
    
      <p className="mb-4">Windsurf is Codeium's AI-powered IDE.</p>

      <ol className="list-decimal list-inside space-y-2 mb-3">
        <li>Open Windsurf Settings → MCP</li>
        <li>Add the server configuration below</li>
      </ol>

      
        <Code language="json" code={`{
  "mcpServers": {
    "bento": {
      "command": "npx",
      "args": ["-y", "@bentonow/bento-mcp"],
      "env": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  }
}`} />
      
    
  

  
    
      <div className="flex items-center gap-3">
        
        <span>OpenCode</span>
      </div>
    
    
      <p className="mb-4">OpenCode is an open-source terminal-based AI coding assistant.</p>

      <p className="mb-2">Add to your <code>opencode.json</code>:</p>
      
        <Code language="json" code={`{
  "mcp": {
    "bento": {
      "type": "local",
      "command": ["npx", "-y", "@bentonow/bento-mcp"],
      "environment": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  }
}`} />
      
    
  

  
    
      <div className="flex items-center gap-3">
        
        <span>Zed</span>
      </div>
    
    
      <p className="mb-4">Zed is a high-performance code editor with AI features.</p>

      <p className="mb-2">Open Zed Settings → Extensions or:</p>
      <pre className="bg-zinc-900 rounded px-3 py-2 text-xs mb-3 overflow-x-auto">~/.config/zed/settings.json</pre>

      <p className="mb-2">Add under <code>context_servers</code>:</p>
      
        <Code language="json" code={`{
  "context_servers": {
    "bento": {
      "command": {
        "path": "npx",
        "args": ["-y", "@bentonow/bento-mcp"]
      },
      "env": {
        "BENTO_PUBLISHABLE_KEY": "your-publishable-key",
        "BENTO_SECRET_KEY": "your-secret-key",
        "BENTO_SITE_UUID": "your-site-uuid"
      }
    }
  }
}`} />
      
    
  


---


## Available Tools


The MCP server provides these tools that your AI assistant can use:

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose my-6">
  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-emerald-400 uppercase tracking-wide font-medium">Subscriber Management</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Look up john@example.com in Bento"</p>
        <p className="text-zinc-400 text-sm mb-1">Look up a subscriber by email or UUID</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">get_subscriber</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Import these 50 subscribers with the 'webinar-attendee' tag"</p>
        <p className="text-zinc-400 text-sm mb-1">Import up to 1000 subscribers at once</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">batch_import_subscribers</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-blue-400 uppercase tracking-wide font-medium">Tags</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"What tags do I have in Bento?"</p>
        <p className="text-zinc-400 text-sm mb-1">List all tags in your account</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">list_tags</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Create a tag called 'vip-customer'"</p>
        <p className="text-zinc-400 text-sm mb-1">Create a new tag</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">create_tag</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-violet-400 uppercase tracking-wide font-medium">Custom Fields</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Show me my custom fields in Bento"</p>
        <p className="text-zinc-400 text-sm mb-1">List all custom fields</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">list_fields</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Create a custom field for 'company_name'"</p>
        <p className="text-zinc-400 text-sm mb-1">Create a new custom field</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">create_field</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-amber-400 uppercase tracking-wide font-medium">Event Tracking</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Track a 'completed_onboarding' event for user@example.com"</p>
        <p className="text-zinc-400 text-sm mb-1">Track a custom event (can trigger automations)</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">track_event</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-pink-400 uppercase tracking-wide font-medium">Broadcasts</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Show me my recent broadcasts"</p>
        <p className="text-zinc-400 text-sm mb-1">List all broadcasts/campaigns</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">list_broadcasts</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Create a broadcast for our spring sale announcement"</p>
        <p className="text-zinc-400 text-sm mb-1">Create a new draft broadcast</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">create_broadcast</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-cyan-400 uppercase tracking-wide font-medium">Automations</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"What automations do I have set up?"</p>
        <p className="text-zinc-400 text-sm mb-1">List all automations — filter by sequences, workflows, or all</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">list_automations</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-indigo-400 uppercase tracking-wide font-medium">Sequences</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Show me all my email sequences"</p>
        <p className="text-zinc-400 text-sm mb-1">List email sequences with their email templates</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">list_sequences</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Add a new email to my Welcome Series sequence about setting up their profile"</p>
        <p className="text-zinc-400 text-sm mb-1">Create a new email in a sequence by ID or name</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">create_sequence_email</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Update the subject line on sequence email template 456"</p>
        <p className="text-zinc-400 text-sm mb-1">Update a sequence email's subject or HTML content</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">update_sequence_email</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-rose-400 uppercase tracking-wide font-medium">Workflows</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Show me my workflows"</p>
        <p className="text-zinc-400 text-sm mb-1">List workflows with their status and email templates</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">list_workflows</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-orange-400 uppercase tracking-wide font-medium">Email Templates</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"Show me template ID 123"</p>
        <p className="text-zinc-400 text-sm mb-1">Get an email template's content by ID</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">get_email_template</code>
      </div>
      <div>
        <p className="text-white text-sm font-medium mb-1">"Update template 123 with this new subject line"</p>
        <p className="text-zinc-400 text-sm mb-1">Update a template's subject or content</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">update_email_template</code>
      </div>
    </div>
  </div>

  <div className="p-5 bg-[#14120b] border border-[#222] rounded-lg">
    <span className="text-xs text-teal-400 uppercase tracking-wide font-medium">Statistics</span>
    <div className="mt-3 space-y-4">
      <div>
        <p className="text-white text-sm font-medium mb-1">"How many subscribers do I have?"</p>
        <p className="text-zinc-400 text-sm mb-1">Get overall site statistics</p>
        <code className="text-xs text-zinc-500 bg-zinc-800/50 px-1.5 py-0.5 rounded">get_site_stats</code>
      </div>
    </div>
  </div>
</div>

---


## Common Workflows


## Creating an Email Broadcast

This is the most common workflow—drafting and creating an email campaign using natural language.


  
    Create a broadcast called 'Summer Sale Announcement' with the subject 'Save 30% This Weekend Only'. Use HTML format. Send from 'Marketing Team' at marketing@mycompany.com. The content should announce our summer sale with a 30% discount code SUMMER30.
  
  
    I'll create that broadcast for you.
  
  
    Created draft broadcast "Summer Sale Announcement"
    The broadcast is now saved as a draft in your Bento dashboard.
  


> Broadcasts created via MCP are always saved as drafts. You'll need to review and send them from the Bento dashboard. This is a safety feature to prevent accidental sends.


---

## Importing Subscribers

Perfect for moving subscribers from a spreadsheet or another platform.


  
    Import these subscribers with the tag 'newsletter-2024':
    <br/><span className="text-zinc-500">•</span> alice@example.com (Alice Smith)
    <br/><span className="text-zinc-500">•</span> bob@example.com (Bob Jones)
    <br/><span className="text-zinc-500">•</span> carol@example.com (Carol Williams)
  
  
    I'll import those 3 subscribers with the 'newsletter-2024' tag.
  
  
    Successfully imported 3 of 3 subscribers
  


**Pro Tips for Bulk Imports:**
- You can import up to 1000 subscribers at once
- Custom fields are supported—just mention them naturally
- Tags can be added or removed during import
- Existing subscribers will be updated (not duplicated)

---

## Tracking Purchase Events

Track revenue and trigger purchase-based automations.


  
    Track a $49.99 purchase for customer@example.com. Order ID is ORD-12345, product is 'Annual Pro Plan'.
  
  
    I'll track that purchase event.
  
  
    Tracked event "$purchase" for customer@example.com
  


> ⚠️ **Warning**
> **Purchase Event Requirements:** Purchase events must include:
> - `value.amount`: Amount in cents (4999 for $49.99)
> - `value.currency`: ISO currency code (USD, EUR, etc.)
> - `unique.key`: A unique identifier to prevent double-counting (order ID)
> 
> The MCP server will auto-generate a unique key if you don't provide one, but using your order ID is recommended.


---

## Checking Your Stats

Get a quick overview of your Bento account performance.


  
    How is my Bento account doing? Give me the key stats.
  
  
    Retrieved site statistics
    
  
  
    Your Bento account is healthy! You have 12,547 total subscribers with 95% active. Your average open rate of 42.3% is well above industry average.
  


---

## Managing Your Subscriber Data

Look up and understand your subscribers.


  
    Look up john.doe@example.com and tell me everything about them
  
  
    Found subscriber
    
  
  
    John Doe is an active VIP customer from Acme Corp on the Enterprise plan. He's been subscribed since January 2024 and has the newsletter and customer tags.
  


---

## Setting Up Custom Fields

Create the data structure for personalization.


  
    I need to track company name, job title, and plan type for my subscribers. Create those fields.
  
  
    I'll create those three custom fields for you.
  
  
    Created field "company_name"
    Created field "job_title"
    Created field "plan_type"
    Fields are now available for use when importing subscribers or tracking events.
  


---

## Building a Welcome Sequence

Create and populate an email sequence step by step using natural language.


  
    Show me my sequences in Bento—I want to add emails to my welcome series.
  
  
    Found 3 sequences
    
  
  
    I found your Welcome Series. I'll add a new email to it.
  
  
    Created email "Complete Your Profile" in Welcome Series
    Set delivery timing with the delayInterval and delayIntervalCount parameters, or adjust in the Bento dashboard after creation.
  


> You can reference a sequence by its name (case-insensitive) or ID. When updating sequence email HTML later, you must include `{"{{ visitor.unsubscribe_url }}"}` for compliance.


---

## Reviewing Workflows

Check on your workflow performance and email templates.


  
    Show me my workflows and how they're performing.
  
  
    Found 2 workflows
    
  
  
    You have 2 workflows. Post-Purchase Follow-up is live with 3 email templates. Trial Expiry Reminder is still in draft with 2 emails — you can activate it from the Bento dashboard when ready.
  


---


## Troubleshooting


  
    
  
  
    <div className="rounded-lg bg-neutral-800/70 p-4 mt-0 pt-1">
      <h4 className="text-white font-semibold text-lg mb-3">Testing Your Connection</h4>

      <p className="text-zinc-300 text-sm mb-3">Run the server manually to check for errors:</p>

      
        <Code language="bash" code={`BENTO_PUBLISHABLE_KEY=xxx \\
BENTO_SECRET_KEY=xxx \\
BENTO_SITE_UUID=xxx \\
npx @bentonow/bento-mcp`} />
      

      <p className="text-zinc-300 text-sm mb-3 mt-4">Or ask your AI assistant:</p>

      
        
      

      <p className="text-zinc-300 text-sm mt-4">If it works, you'll see your tags. If not, check your configuration.</p>
    </div>
  


---


## Best Practices


### Security

- **Never share your Secret Key** in public repositories, screenshots, or support tickets
- **Use environment variables** in CI/CD rather than hardcoding credentials
- **Rotate API keys periodically**, especially if you suspect they may have been exposed

### Performance

- **Use batch operations** when importing multiple subscribers—`batch_import_subscribers` handles up to 1000 at once
- **Be specific in your prompts** to help the AI choose the right tool on the first try
- **Review broadcasts in Bento** before sending—the MCP creates drafts for safety

### Workflow Tips

- **Start with stats** to understand your account state before making changes
- **Test with a single subscriber** before bulk importing
- **Use descriptive broadcast names** so they're easy to find in the Bento dashboard
- **Leverage custom fields** for personalization—create them once, use them everywhere

### Sequences & Workflows

- **Always include an unsubscribe URL** when updating sequence email HTML—use `{"{{ visitor.unsubscribe_url }}"}` (required by the update tools for compliance)
- **Reference sequences by name** for readability, or by ID for precision
- **Set delivery timing explicitly** when creating sequence emails using `delayInterval` and `delayIntervalCount`—no default delay is applied
- **Use `list_automations` with a type filter** to narrow results to just sequences or just workflows

---


## Quick Reference Card


### Subscriber Operations

```
"Look up [email] in Bento"
"Import these subscribers with tag [tag]: [list]"
```

### Tag Operations

```
"What tags do I have?"
"Create a tag called [name]"
```

### Broadcast Operations

```
"Show me my broadcasts"
"Create a broadcast called [name] about [topic]"
```

### Sequence Operations

```
"Show me my sequences"
"Add an email to my [sequence name] sequence about [topic]"
"Update the subject on sequence email [id]"
```

### Workflow Operations

```
"Show me my workflows"
"List only my workflows"
```

### Event Tracking

```
"Track [event] for [email]"
"Log a $[amount] purchase for [email]"
```

### Statistics

```
"Show me my Bento stats"
"How many subscribers do I have?"
```

---


## Environment Variable Approach (Advanced)


For users who prefer not to store credentials in config files:

**1. Add to your shell profile (`~/.zshrc` or `~/.bashrc`):**


  <Code language="bash" code={`export BENTO_PUBLISHABLE_KEY="pk_live_..."
export BENTO_SECRET_KEY="sk_live_..."
export BENTO_SITE_UUID="..."`} />


**2. Use a simpler MCP config:**


  <Code language="json" code={`{
  "mcpServers": {
    "bento": {
      "command": "npx",
      "args": ["-y", "@bentonow/bento-mcp"]
    }
  }
}`} />


The server will automatically pick up the environment variables from your shell.

---


## Get Help


- **GitHub Issues**: [github.com/bentonow/bento-mcp/issues](https://github.com/bentonow/bento-mcp/issues)
- **Documentation**: [docs.bentonow.com](https://docs.bentonow.com)
- **Discord**: [Join the community](https://discord.gg/ssXXFRmt5F)
- **Email Support**: support@bentonow.com

---


## Links


- [GitHub Repository](https://github.com/bentonow/bento-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Bento Node SDK](/docs/examples/nodejs)
- [API Reference](/docs/developer_guides/introduction)