Instantly

by bcharleson

1 stars

Not rated

GitHub

About

Integrates with Instantly API v2 to enable email campaign management, lead tracking, and account health monitoring for automated outreach workflows.

Details

Author: bcharleson
Repository: bcharleson/instantly-mcp
GitHub stars: 1
License: MIT License
Categories: Productivity, Design, Developer Tools, AI, Infrastructure, Automation, API, Frontend, Communication, Other

- 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

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Instantly

Command (node, npx, python, etc.) python
Arguments
- Argument 1 -m
- Argument 2 instantly_mcp.server
Environment
- INSTANTLY_API_KEY your-api-key-here
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

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

pip install -e .

pip install fastmcp httpx pydantic python-dotenv

bash

The server supports multiple authentication methods for flexibility:

Include your API key directly in the URL path:

```

`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.

`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.

`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.

`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.

`get_campaign_analytics`

Campaign metrics (opens, clicks, replies).

`get_daily_campaign_analytics`

Day-by-day performance.

`get_warmup_analytics`

Account warmup metrics.

`list_background_jobs`

List async background jobs with pagination.

`get_background_job`

Get details of a specific background job.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

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

- 38 toolsacross 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

# 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

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

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

# Using FastMCP CLI fastmcp run src/instantly_mcp/server.py # Using Python directly python -m instantly_mcp.server

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

The server supports multiple authentication methods for flexibility:

Include your API key directly in the URL path:

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

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

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

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

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

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

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

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

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

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

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"

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"]

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"}'

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)" } }

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" } }

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

For detailed API documentation, see:Instantly V2 API Docs

Contributions welcome! Please open an issue or PR.

Webinar intelligence for Zoom Meeting-based webinars: Query funnels, registrations, transcripts, and email engagement with 16 tools via OAuth 2.1

Manage Smartlead campaigns, including creation, updates, and sequence management, using the Smartlead API.

Manage email campaigns on Woodpecker using natural language.

Turn AI tools into your email marketing assistant.

Turn an AI tool into your smart email engine

Integrates with the HeyReach API for LinkedIn automation and outreach management.

Kraiter is an email automation platform. It exposes 62 tools for managing contacts, drip campaigns, transactional sends, segments, templates, domains, and metrics.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

list_accounts

get_account

create_account

update_account

manage_account_state

delete_account

create_campaign

list_campaigns

get_campaign

update_campaign

activate_campaign

pause_campaign

delete_campaign

search_campaigns_by_contact

list_leads

get_lead

create_lead

update_lead

list_lead_lists

create_lead_list

update_lead_list

get_verification_stats_for_lead_list

add_leads_to_campaign_or_list_bulk

delete_lead

delete_lead_list

move_leads_to_campaign_or_list

list_emails

get_email

reply_to_email

count_unread_emails

verify_email

mark_thread_as_read

get_campaign_analytics

get_daily_campaign_analytics

get_warmup_analytics

list_background_jobs

get_background_job

Claude Desktop / Cursor

Linux

Macos

Windows

HTTP Mode (Recommended for Remote Deployment)

Lazy Loading (Context Window Optimization)

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7

`list_accounts`

`get_account`

`create_account`

`update_account`

`manage_account_state`

`delete_account`

`create_campaign`

`list_campaigns`

`get_campaign`

`update_campaign`

`activate_campaign`

`pause_campaign`

`delete_campaign`

`search_campaigns_by_contact`

`list_leads`

`get_lead`

`create_lead`

`update_lead`

`list_lead_lists`

`create_lead_list`

`update_lead_list`

`get_verification_stats_for_lead_list`

`add_leads_to_campaign_or_list_bulk`

`delete_lead`

`delete_lead_list`

`move_leads_to_campaign_or_list`

`list_emails`

`get_email`

`reply_to_email`

`count_unread_emails`

`verify_email`

`mark_thread_as_read`

`get_campaign_analytics`

`get_daily_campaign_analytics`

`get_warmup_analytics`

`list_background_jobs`

`get_background_job`