emailbison-mcp-server

laviefatigue/emailbison-mcp-server

3.2

If you are the rightful owner of emailbison-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Email Bison MCP Server v3.1.1 is a portable distribution designed for strategic email campaign management, providing a suite of tools for integration with Claude Desktop.

Tools
5
Resources
0
Prompts
0

Email Bison MCP Server v3.1.1 - Portable Distribution

Version: 3.1.1 Release Date: October 25, 2025 Status: ✅ Production Ready - Validated with 100% accuracy

What's Included

This is a complete, portable installation of the Email Bison MCP Server that you can share with your team for one-click deployment into Claude Desktop.

Package Contents:

  • ✅ Complete source code with v3.1.1 bug fixes
  • ✅ All 25 production-ready MCP tools
  • ✅ Configuration templates
  • ✅ Setup instructions
  • ✅ Requirements file

What This MCP Server Does

The Email Bison MCP Server provides strategic intelligence for email campaign management directly within Claude Desktop/Code. It connects to your Email Bison account and exposes 25 tools organized into 4 categories:

📊 Core Foundation (4 tools)

  • Connection testing
  • Workspace listing
  • Inbox summaries with health scores
  • Provider distribution analysis

🏗️ Infrastructure Intelligence (11 tools)

  • Health monitoring and trends
  • Capacity planning
  • Anomaly detection
  • Warmup status tracking
  • Rotation activity logs

📈 Campaign Intelligence (8 tools)

  • Performance metrics and ROI
  • Funnel analysis
  • A/B test comparisons
  • Copy performance analysis
  • Campaign comparisons

🔧 Operational Tools (2 tools)

  • Workspace summaries
  • Performance reporting
  • Reply analysis
  • Lead search

🚀 One-Click Setup Instructions

Prerequisites

  1. Python 3.11+ installed
  2. Claude Desktop installed
  3. Email Bison API Token (get from your Email Bison account settings)

Step 1: Install Python Dependencies

Open a terminal/command prompt in this directory and run:

pip install -r requirements.txt

This installs:

  • mcp - Model Context Protocol SDK
  • httpx - HTTP client for API calls
  • pydantic - Data validation
  • python-dotenv - Environment variable management
  • cachetools - Response caching

Step 2: Configure Claude Desktop

  1. Locate your Claude Desktop config file:

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

  2. Edit the config file and add this section inside the "mcpServers" object:

IMPORTANT: Replace YOUR_PATH_HERE with the absolute path to this portable directory.

{
  "mcpServers": {
    "emailbison": {
      "command": "python",
      "args": [
        "-m",
        "emailbison_mcp.server_complete"
      ],
      "cwd": "YOUR_PATH_HERE/emailbison-mcp-v3.1.1-portable",
      "env": {
        "PYTHONPATH": "YOUR_PATH_HERE/emailbison-mcp-v3.1.1-portable/src",
        "EMAILBISON_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "EMAILBISON_API_URL": "https://spellcast.hirecharm.com"
      }
    }
  }
}

Example (Windows):

"emailbison": {
  "command": "python",
  "args": ["-m", "emailbison_mcp.server_complete"],
  "cwd": "C:\\Users\\john\\Desktop\\emailbison-mcp-v3.1.1-portable",
  "env": {
    "PYTHONPATH": "C:\\Users\\john\\Desktop\\emailbison-mcp-v3.1.1-portable\\src",
    "EMAILBISON_API_TOKEN": "16|YOUR_ACTUAL_TOKEN_HERE",
    "EMAILBISON_API_URL": "https://spellcast.hirecharm.com"
  }
}

Example (Mac/Linux):

"emailbison": {
  "command": "python3",
  "args": ["-m", "emailbison_mcp.server_complete"],
  "cwd": "/Users/john/Desktop/emailbison-mcp-v3.1.1-portable",
  "env": {
    "PYTHONPATH": "/Users/john/Desktop/emailbison-mcp-v3.1.1-portable/src",
    "EMAILBISON_API_TOKEN": "16|YOUR_ACTUAL_TOKEN_HERE",
    "EMAILBISON_API_URL": "https://spellcast.hirecharm.com"
  }
}

Step 3: Get Your Email Bison API Token

  1. Log into Email Bison (https://spellcast.hirecharm.com)
  2. Go to Account Settings → API Tokens
  3. Create a new token or copy an existing one
  4. Paste it into the config file where it says YOUR_API_TOKEN_HERE

Step 4: Restart Claude Desktop

  1. Completely close Claude Desktop (File → Exit, not just close window)
  2. Reopen Claude Desktop
  3. The MCP server will automatically start in the background

Step 5: Test the Connection

In Claude Desktop, send this message:

Use the Email Bison MCP test_connection tool

You should see output confirming the connection is successful, showing your workspaces.

🎯 Quick Start Examples

Get Campaign Performance

Use the Email Bison MCP tool get_campaign_list with intelligence_mode=true to show me top performing campaigns

Analyze Campaign Copy

Use get_copy_performance_unified to analyze email copy performance for "Campaign 001"

Check Inbox Health

Use get_inbox_summary to show me all my inboxes with health scores

Monitor Infrastructure

Use get_infrastructure_overview with intelligence_mode=true for a complete system snapshot

⚡ Intelligence Mode Explained

Most tools have an intelligence_mode parameter:

intelligence_mode=True (Default)

  • Returns top 10 + summary statistics
  • Uses ~500-4,000 tokens (2-20% of context window)
  • Fast and efficient for dashboards and multi-turn conversations
  • Recommended for most use cases

intelligence_mode=False

  • Returns all data (50+ campaigns, 100+ replies, etc.)
  • Uses ~5,000-70,000 tokens (3-35% of context window)
  • Use for deep analysis, data exports, or audits
  • May exhaust context window - use sparingly

Example:

# Quick insights (intelligence mode)
get_campaign_list(workspace_name="Charm")  # Returns top 10, ~500 tokens

# Full data export
get_campaign_list(workspace_name="Charm", intelligence_mode=False)  # Returns all 50, ~5,000 tokens

🔧 Troubleshooting

Issue: "Not connected" error

Solution: Check your API token is correct in the config file.

Use the Email Bison MCP test_connection tool

If this fails, verify:

  1. API token is valid (check Email Bison settings)
  2. API URL is correct: https://spellcast.hirecharm.com
  3. You have internet connectivity

Issue: Tools not showing up in Claude Desktop

Solution:

  1. Verify config file path is correct (check for typos)
  2. Ensure PYTHONPATH points to the src directory
  3. Restart Claude Desktop completely (File → Exit, then reopen)
  4. Check Claude Desktop logs: %APPDATA%\Claude\logs\mcp-server-emailbison.log

Issue: Python module not found

Solution:

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Issue: Incorrect campaign metrics

Solution: This version (v3.1.1) has fixed the calculation bug. Ensure you're running v3.1.1 by checking:

Use test_connection tool - look for "server_version": "3.1.1" in the response

📊 What's New in v3.1.1

✅ Critical Bug Fix: Campaign Metrics

Issue: Campaign metrics were calculated using emails_sent (includes follow-ups) instead of total_leads_contacted (unique contacts).

Impact: Reply rates, bounce rates, and other engagement metrics were underreported by ~50%.

Fix: All percentage calculations now use the correct denominator:

  • Reply rate: unique_replies / total_leads_contacted × 100
  • Bounce rate: bounced / total_leads_contacted × 100
  • Open rate: unique_opens / total_leads_contacted × 100

Validation: 100% pass rate across 12 comprehensive accuracy tests.

✅ Tool Consolidation (30 → 25 tools)

Removed 5 redundant tools that overlapped with more powerful alternatives:

  • get_quick_stats → Use get_infrastructure_overview(intelligence_mode=True)
  • get_disconnected_inboxes → Use get_inbox_summary(status_filter="Not connected")
  • get_health_score_distribution → Use get_inbox_summary(intelligence_mode=True)
  • get_campaign_email_copy → Use get_copy_performance_unified
  • get_campaign_email_performance → Use get_copy_performance_unified

Result: 575 lines of code removed, 52-62% token savings, no functionality lost.

✅ Runtime Token Warnings

Added proactive warnings to high-consumption tools:

  • get_recent_replies: Warns when intelligence_mode=False (saves 71% tokens)
  • analyze_reply_sentiment: Warns when intelligence_mode=False (saves 95% tokens)

Purpose: Prevent accidental context overflow by alerting users BEFORE high-token operations execute.

📁 Directory Structure

emailbison-mcp-v3.1.1-portable/
├── src/
│   └── emailbison_mcp/
│       ├── __init__.py
│       ├── server_complete.py    # Main MCP server (25 tools)
│       ├── api_client.py         # Email Bison API client
│       ├── models.py             # Data models
│       ├── utils.py              # Helper functions
│       └── token_estimator.py   # Token usage tracking
├── requirements.txt              # Python dependencies
└── README.md                     # This file

🔐 Security Notes

  1. API Token Security: Your API token is stored in the Claude Desktop config file. This file is stored locally on your machine and is not transmitted anywhere except to Email Bison's API.

  2. Local Processing: The MCP server runs locally on your machine as a subprocess of Claude Desktop. No data is sent to third parties.

  3. Token Permissions: Use a read-only API token if available. The MCP server only queries data; it doesn't modify campaigns or send emails.

🐳 Alternative Deployment: Docker + Coolify

New in v3.1.1: Remote deployment support via Docker and Coolify!

If you already have a Coolify instance running, you can deploy the Email Bison MCP Server as a remote HTTP service instead of a local subprocess. This enables:

✅ Multi-device access - Use from any machine with Claude Desktop ✅ Team sharing - Deploy once, everyone connects ✅ Zero per-machine setup - No Python installation needed on client machines ✅ Consistent with remote MCP architecture - Same patterns as Coolify MCP

When to Use Remote Deployment

Use Coolify deployment IF:

  • You already have Coolify running (marginal cost = $0)
  • You want CEO/team to access from multiple devices
  • You prefer centralized deployment over per-machine setup

Use local stdio IF:

  • Single-user, single-machine setup
  • Maximum performance (<10ms vs 100-200ms)
  • Simpler security model (localhost only)

Quick Start

  1. Files created for you:

    • ✅ Dockerfile - Container definition
    • ✅ .dockerignore - Build optimization
    • ✅ Server auto-detects deployment mode (stdio vs HTTP)

  2. Follow the deployment guide:

    • See for complete instructions
    • Estimated deployment time: 20-30 minutes
    • Test locally first: Run test-docker-build.bat

  3. Environment variables needed:

    • See for complete reference
    • Required: EMAILBISON_API_TOKEN, EMAILBISON_API_URL, MCP_TRANSPORT=http

Both Deployments Can Coexist

You can run both local (stdio) and remote (HTTP) simultaneously:

  • Local: Fast, for development/testing
  • Remote: Accessible, for production/CEO use

Claude Desktop shows both as available connectors.

📞 Support

Issues or Questions:

  • Check the troubleshooting section above
  • Review Claude Desktop logs: %APPDATA%\Claude\logs\mcp-server-emailbison.log
  • Verify your Email Bison API token is valid

Version Information:

  • Server Version: v3.1.1
  • Release Date: October 25, 2025
  • Python: 3.11+ required
  • Claude Desktop: Latest version recommended

📄 License & Distribution

This MCP server is designed for internal team use at HireCharm. Distribution to external parties requires approval.

Distribution Checklist:

  • ✅ Remove any hardcoded API tokens from config examples
  • ✅ Ensure team members update their own API tokens
  • ✅ Verify Python 3.11+ is installed on recipient machines
  • ✅ Confirm Claude Desktop is installed and up-to-date

🎉 You're all set! Enjoy strategic Email Bison intelligence directly in Claude Desktop.