Instantly

You run an MCP server that exposes the Instantly V2 API to tools and clients. It lets you perform accounts, campaigns, leads, emails, analytics, and background job operations through a lightweight, Python-based MCP server with lazy loading, per-request API keys, and robust error handling.

How to use

You connect to the MCP server using your preferred MCP client. Run the local stdio server to start, or deploy a remote HTTP instance if you have an HTTP endpoint. Once running, your client can invoke the available tool categories (accounts, campaigns, leads, emails, analytics, background_jobs) to manage data and perform actions across your Instantly setup.

How to install

Prerequisites: Python 3.11+ and pip. You may also want to use a virtual environment to keep dependencies isolated.

1. Open a terminal and navigate to your project directory.

2. Install in editable mode so you can edit code during development.

3. Install runtime dependencies.

Additional configuration and startup notes

Set your Instantly API key to enable authenticated requests. You can provide it via environment variable or per-request headers when using HTTP mode.

The server supports two startup modes. For local development, run the stdio mode. For remote deployments, you can expose an HTTP endpoint.

Lazy loading and tenancy

Use lazy loading to reduce context window usage by loading only the categories you need. For example, load accounts and campaigns together, or leads and analytics separately.

Authentication and security

The server accepts per-request API keys. In HTTP mode, you can pass the key via a header or in the URL path. In multi-tenant setups, every request carries the per-request API key for proper isolation.

Rate limiting and errors

The server tracks rate limits automatically from API response headers and surfaces detailed error messages to help you troubleshoot misconfigurations or invalid keys.

Project structure and tooling reference

The codebase provides a FastMCP-based Python server, a client, Pydantic models for validation, and tool implementations organized by category (accounts, campaigns, leads, emails, analytics, background_jobs). You will find lazy loading logic under the tools module and a minimal HTTP transport for remote deployments.

Starting the stdio server (local development)

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

Starting the HTTP server (remote deployment)

Configure a remote HTTP deployment by running the server with the HTTP transport and exposing a port. Use the HTTP deployment for remote access by clients that support HTTP MCP transport.

Environment and quick-start variables

Set your API key before starting the server. You can export it in the shell or provide it through environment-specific configuration.

Troubleshooting tips

If you encounter authentication errors, verify that the INSTANTLY_API_KEY value is correct and that the key is sent with requests in the expected header or URL path.

Available tools

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