Instantly MCP Server (Python)

A lightweight, robust Model Context Protocol (MCP) server for the Instantly.ai V2 API, built with FastMCP.

Features

• 38 tools across 6 categories (accounts, campaigns, leads, emails, analytics, background_jobs)
• Dual transport support: HTTP (remote deployment) + stdio (local)
• Lazy loading: Reduce context window by loading only specific tool categories
• Multi-tenant support: Per-request API keys for HTTP deployments
• Comprehensive error handling: Detailed, actionable error messages
• Rate limiting: Automatic tracking from API response headers
• Dynamic timeouts: Extended timeouts for search and bulk operations

Quick Start

Installation

# Clone or navigate to the repository
cd instantly-mcp-python

# Install with pip
pip install -e .

# Or install dependencies directly
pip install fastmcp httpx pydantic python-dotenv

Configuration

Set your Instantly API key:

export INSTANTLY_API_KEY="your-api-key-here"

Or create a .env file:

INSTANTLY_API_KEY=your-api-key-here

Running the Server

HTTP Mode (Recommended for Remote Deployment)

# Using FastMCP CLI
fastmcp run src/instantly_mcp/server.py --transport http --port 8000

# Using Python directly
python -m instantly_mcp.server --transport http --port 8000

# Or with uvicorn for production
uvicorn instantly_mcp.server:mcp.app --host 0.0.0.0 --port 8000

stdio Mode (Local Development)

# Using FastMCP CLI
fastmcp run src/instantly_mcp/server.py

# Using Python directly
python -m instantly_mcp.server

Tool Categories

Accounts (6 tools)

Tool	Description
list_accounts	List email accounts with filtering
get_account	Get account details and warmup status
create_account	Create account with IMAP/SMTP credentials
update_account	Update account settings
manage_account_state	Pause, resume, warmup control, test vitals
delete_account	⚠️ Permanently delete account

Campaigns (8 tools)

Tool	Description
create_campaign	Create email campaign (two-step process)
list_campaigns	List campaigns with pagination
get_campaign	Get campaign details and sequences
update_campaign	Update campaign settings
activate_campaign	Start campaign sending
pause_campaign	Stop campaign sending
delete_campaign	⚠️ Permanently delete campaign
search_campaigns_by_contact	Find campaigns a contact is enrolled in

Leads (12 tools)

Tool	Description
list_leads	List leads with filtering
get_lead	Get lead details
create_lead	Create single lead
update_lead	Update lead (⚠️ custom_variables replaces all)
list_lead_lists	List lead lists
create_lead_list	Create lead list
update_lead_list	Update lead list
get_verification_stats_for_lead_list	Get email verification stats
add_leads_to_campaign_or_list_bulk	Bulk add up to 1,000 leads
delete_lead	⚠️ Permanently delete lead
delete_lead_list	⚠️ Permanently delete lead list
move_leads_to_campaign_or_list	Move/copy leads between campaigns/lists

Emails (6 tools)

Tool	Description
list_emails	List emails with filtering
get_email	Get email details
reply_to_email	🚨 Send real email reply
count_unread_emails	Count unread inbox emails
verify_email	Verify email deliverability
mark_thread_as_read	Mark email thread as read

Analytics (3 tools)

Tool	Description
get_campaign_analytics	Campaign metrics (opens, clicks, replies)
get_daily_campaign_analytics	Day-by-day performance
get_warmup_analytics	Account warmup metrics

Background Jobs (2 tools)

Tool	Description
list_background_jobs	List async background jobs with pagination
get_background_job	Get details of a specific background job

Lazy Loading (Context Window Optimization)

Reduce context window usage by loading only the categories you need:

# Load only accounts and campaigns (14 tools instead of 38)
export TOOL_CATEGORIES="accounts,campaigns"

# Load only leads and analytics
export TOOL_CATEGORIES="leads,analytics"

Valid categories: accounts, campaigns, leads, emails, analytics, background_jobs

Authentication Methods

The server supports multiple authentication methods for flexibility:

1. URL-based Authentication

Include your API key directly in the URL path:

https://your-server.com/mcp/YOUR_API_KEY

2. Header Authentication

URL: https://your-server.com/mcp
Header: Authorization: YOUR_API_KEY

Note: Bearer token prefix is optional

3. Custom Header

URL: https://your-server.com/mcp
Header: x-instantly-api-key: YOUR_API_KEY

4. Environment Variable

export INSTANTLY_API_KEY="your-api-key-here"

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

stdio Mode (Local)

{
  "mcpServers": {
    "instantly": {
      "command": "python",
      "args": ["-m", "instantly_mcp.server"],
      "env": {
        "INSTANTLY_API_KEY": "your-api-key-here"
      }
    }
  }
}

HTTP Mode with URL Auth (Recommended)

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp/YOUR_API_KEY"
    }
  }
}

HTTP Mode with Header Auth

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "your-api-key-here"
      }
    }
  }
}

Cursor IDE

Add to ~/.cursor/mcp.json:

With URL Authentication

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp/YOUR_API_KEY"
    }
  }
}

With Header Authentication

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "x-instantly-api-key": "your-api-key-here"
      }
    }
  }
}

DigitalOcean App Platform Deployment

App Spec

name: instantly-mcp
services:
  - name: instantly-mcp
    source:
      git:
        branch: main
        repo_clone_url: https://github.com/your-username/instantly-mcp-python.git
    build_command: pip install -e .
    run_command: python -m instantly_mcp.server --transport http --port 8080
    http_port: 8080
    instance_size_slug: basic-xxs
    instance_count: 1
    envs:
      - key: INSTANTLY_API_KEY
        scope: RUN_TIME
        type: SECRET
      - key: PORT
        scope: RUN_TIME
        value: "8080"

Dockerfile (Alternative)

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml .
COPY src/ src/

RUN pip install -e .

EXPOSE 8000

CMD ["python", "-m", "instantly_mcp.server", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

Multi-Tenant HTTP Mode

For deployments serving multiple users, the server supports per-request API keys:

# Start server without default API key
python -m instantly_mcp.server --transport http --port 8000

# Clients provide API key via header
curl -X POST http://localhost:8000/mcp \
  -H "x-instantly-api-key: user-specific-api-key" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Error Handling

The server provides detailed, actionable error messages:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Instantly API key is required. Provide via:\n  - INSTANTLY_API_KEY environment variable\n  - api_key parameter\n  - x-instantly-api-key header (HTTP mode)"
  }
}

Rate Limiting

The server automatically tracks rate limits from API response headers:

# Access via get_server_info tool
{
  "rate_limit": {
    "remaining": 95,
    "limit": 100,
    "reset_at": "2024-01-15T12:00:00"
  }
}

Project Structure

instantly-mcp-python/
├── src/
│   └── instantly_mcp/
│       ├── __init__.py          # Package exports
│       ├── server.py            # FastMCP server (~180 lines)
│       ├── client.py            # API client (~200 lines)
│       ├── models/              # Pydantic models
│       │   ├── __init__.py
│       │   ├── common.py        # Pagination
│       │   ├── accounts.py      # Account models
│       │   ├── campaigns.py     # Campaign models
│       │   ├── leads.py         # Lead models
│       │   ├── emails.py        # Email models
│       │   └── analytics.py     # Analytics models
│       └── tools/               # Tool implementations
│           ├── __init__.py      # Lazy loading logic
│           ├── accounts.py      # 6 account tools
│           ├── campaigns.py     # 8 campaign tools
│           ├── leads.py         # 12 lead tools
│           ├── emails.py        # 6 email tools
│           ├── analytics.py     # 3 analytics tools
│           └── background_jobs.py # 2 background job tools
├── pyproject.toml               # Dependencies
├── env.example                  # Environment template
└── README.md                    # This file

Comparison with TypeScript Version

Aspect	TypeScript	Python FastMCP
Lines of Code	~5,000+	~1,500
Tool Registration	Manual handlers	@mcp.tool decorator
Input Validation	Zod schemas	Pydantic (auto)
Error Messages	Manual	Auto from Pydantic
HTTP Server	Custom transport	Built-in
Context Window	Larger schemas	Smaller, cleaner

API Reference

For detailed API documentation, see: Instantly V2 API Docs

License

MIT License

Contributing

Contributions welcome! Please open an issue or PR.