MCP SERVERRun Instantly.ai cold-email operations from a conversation — sending accounts and warmup, campaigns, leads in bulk, inbox replies and campaign analytics.
LABSCO SUMMARY
TOOL_CATEGORIES is the setting to reach for first: most sessions want two categories, not six, and the difference is 14 tool definitions against 38 riding along every turn. Note also which tools act on the outside world — reply_to_email sends a real email, and the delete tools on accounts, campaigns, leads and lead lists are permanent — so decide up front whether this installation is for reading analytics or for running the sending.
A FastMCP server over the Instantly.ai V2 API, covering 38 tools across six categories: accounts, campaigns, leads, emails, analytics and background jobs. It runs locally over stdio or as a remote HTTP deployment, and in HTTP mode it can take a different API key per request so one deployment can serve several tenants.
list_accounts, get_account, create_account, update_account, manage_account_state, delete_accountcreate_campaign, list_campaigns, get_campaign, activate_campaign, pause_campaign, search_campaigns_by_contactlist_leads, create_lead, update_lead, create_lead_list, add_leads_to_campaign_or_list_bulk, move_leads_to_campaign_or_list, get_verification_stats_for_lead_listlist_emails, get_email, count_unread_emails, mark_thread_as_read, verify_email, reply_to_emailget_campaign_analytics, get_daily_campaign_analytics, get_warmup_analyticslist_background_jobs, get_background_jobget_server_infoAn Instantly.ai API key from your account's integrations settings. Locally it goes in INSTANTLY_API_KEY; over HTTP it can travel in the URL path, in an Authorization header, or in an x-instantly-api-key header, which is what makes per-tenant keys possible. The package is instantly-mcp on PyPI (version 1.0.1), installed with pip install -e . and run over stdio or with --transport http. TOOL_CATEGORIES narrows which categories load — setting it to accounts,campaigns gives 14 tools instead of 38.
Build from source — git clone https://github.com/bcharleson/Instantly-MCP.git
USE CASES
Pull campaign analytics for the totals and the day-by-day view, so a dip is visible against the day it started rather than averaged away.
Create the lead list, add up to 1,000 leads in one bulk call, then read the verification stats before you point a campaign at it.
List the sending accounts, read warmup analytics per account, and pause or adjust warmup on the ones whose vitals are off.
Count unread, read the thread, send the reply, and mark the thread read — the whole loop without opening the Instantly interface.
Search campaigns by contact before adding them again, so the same person does not receive two sequences at once.
Move or copy leads from one campaign or list to another and watch the background job until it finishes.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
activate_campaignActivate campaign to start sending.
Prerequisites (all required):
Use get_campaign to verify all prerequisites are met.
add_leads_to_campaign_or_list_bulkBulk add up to 1,000 leads. 10-100x faster than create_lead.
Provide EITHER campaign_id OR list_id (not both).
Each lead requires at minimum an email address. Custom variables must match campaign field definitions.
Use skip_if_in_campaign=true to prevent duplicates (recommended).
count_unread_emailsCount unread emails in inbox.
Returns the total number of unread emails across all accounts. Useful for inbox zero tracking and notification badges.
create_accountCreate email account with IMAP/SMTP credentials.
Provider codes:
Requires valid IMAP and SMTP credentials for email sending.
create_campaignCreate email campaign. Two-step process:
Step 1: Call with name/subject/body to discover available sender accounts Step 2: Call again with email_list to assign senders
Personalization variables:
Use sequence_steps for multi-step follow-up sequences.
IMPORTANT API v2 Structure:
create_leadCreate a single lead with custom variables.
Use skip_if_in_campaign=true to prevent duplicates (recommended).
Custom variables must match field names defined in the campaign. Example: {"industry": "Technology", "company_size": "50-100"}
For bulk imports (10+ leads), use add_leads_to_campaign_or_list_bulk instead.
create_lead_listCreate a lead list.
Set has_enrichment_task=true to enable automatic lead enrichment. Enrichment adds company info, social profiles, and other data.
delete_account🚨 PERMANENTLY delete an email account. CANNOT UNDO!
This action:
Confirm with user before executing!
delete_campaign🚨 PERMANENTLY delete a campaign. CANNOT UNDO!
⚠️ REQUIRES USER CONFIRMATION before executing!
This action:
Before calling this tool, you MUST:
delete_lead🗑️ PERMANENTLY delete a lead. CANNOT UNDO!
This action:
Confirm with user before executing!
delete_lead_list🚨 PERMANENTLY delete a lead list. CANNOT UNDO!
⚠️ REQUIRES USER CONFIRMATION before executing!
This action:
Before calling this tool, you MUST:
get_accountGet account details, warmup status, and campaign eligibility by email.
Returns comprehensive account information including:
get_background_jobGet details of a specific background job by ID.
Returns comprehensive job information including:
Use this to check if a bulk operation has finished.
get_campaignGet campaign details: config, sequences, schedules, sender accounts, tracking, status.
Returns comprehensive campaign information including:
get_campaign_analyticsGet campaign metrics: opens, clicks, replies, bounces.
Filter by campaign(s) and date range. Omit campaign_id to get analytics for all campaigns.
Use campaign_ids array to get analytics for multiple specific campaigns. Set exclude_total_leads_count=true for faster response.
Returns:
get_daily_campaign_analyticsGet day-by-day campaign performance analytics.
Returns daily breakdown of:
Campaign status filter:
Useful for tracking performance trends over time.
get_emailGet email details by ID.
Returns:
get_leadGet lead details by ID.
Returns comprehensive lead information including:
get_server_infoGet Instantly MCP server information.
Returns server version, loaded categories, and configuration status. Useful for debugging and verifying server setup.
get_verification_stats_for_lead_listGet email verification statistics for a lead list.
Returns breakdown of verification results:
get_warmup_analyticsGet warmup metrics for email account(s).
Provide either:
Returns warmup performance data:
Use date filters to analyze specific time periods.
list_accountsList email accounts with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null.
Status codes: 1=Active, 2=Paused, -1/-2/-3=Errors Provider codes: 1=IMAP, 2=Google, 3=Microsoft, 4=AWS
Returns accounts with warmup status and campaign eligibility.
list_background_jobsList background jobs with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null.
Background jobs are created for async operations like:
Job statuses:
Returns list of jobs with status, type, and progress info.
list_campaignsList campaigns with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null.
Note: search filters by campaign NAME only, not by status. To filter by status, use campaign_status in get_daily_campaign_analytics.
Returns campaign list with status, lead counts, and performance metrics.
list_emailsList emails with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null.
Search tips:
Modes:
list_lead_listsList lead lists with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null.
Lead lists are containers for organizing leads outside of campaigns. Use has_enrichment_task filter to find lists with auto-enrichment enabled.
list_leadsList leads with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null.
Filter values:
Use distinct_contacts=true to deduplicate by email.
manage_account_stateManage account state: pause, resume, enable/disable warmup, or test vitals.
Actions:
Use test_vitals to diagnose connection issues.
mark_thread_as_readMark an email thread as read.
Marks all emails in the specified thread as read. Useful for:
Returns confirmation of the action.
move_leads_to_campaign_or_listMove or copy leads between campaigns/lists.
Runs as background job for large operations.
Source selection (use one):
Destination (use one):
Set copy_leads=true to copy instead of move.
pause_campaignPause campaign to stop sending.
Effects:
Use activate_campaign to resume sending.
reply_to_email🚨 SENDS REAL EMAIL! Confirm with user first. Cannot undo!
Sends a reply to an existing email thread.
Requirements:
The reply will be sent immediately and appear in the lead's inbox.
search_campaigns_by_contactFind all campaigns that a specific contact/lead is part of.
Useful for:
Returns list of campaigns the contact email is enrolled in.
update_accountUpdate account settings (partial update).
Common updates:
Only include fields you want to update.
update_campaignUpdate campaign settings (partial update).
Common updates:
Only include fields you want to update.
update_leadUpdate lead (partial update).
⚠️ IMPORTANT: custom_variables REPLACES the entire object! To preserve existing custom variables:
Example: If lead has {"industry": "Tech"} and you want to add {"size": "Large"}, you must pass {"industry": "Tech", "size": "Large"} - not just {"size": "Large"}
update_lead_listUpdate lead list name, enrichment settings, or owner.
verify_emailVerify email deliverability (takes 5-45 seconds).
Initiates a new email verification via POST request. If verification takes longer than 10 seconds, the initial response will have verification_status='pending'. The tool will automatically poll for the final result unless skip_polling=true.
Parameters:
Returns:
BEFORE YOU INSTALL
38 tools when we connected.
INSTANTLY_API_KEY in your environment
Both documented clients run the server on your machine.
CONTEXT COST
Rated by the size of the 38 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
This one is built from source rather than installed with a single command.
git clone https://github.com/bcharleson/Instantly-MCP.git
cd Instantly-MCP
pip install -e .
export INSTANTLY_API_KEY="<YOUR_INSTANTLY_API_KEY>"
python -m instantly_mcp.server{
"mcpServers": {
"instantly": {
"command": "python",
"args": [
"-m",
"instantly_mcp.server"
],
"env": {
"INSTANTLY_API_KEY": "<YOUR_INSTANTLY_API_KEY>"
}
}
}
}Start the server in HTTP mode from your clone first: python -m instantly_mcp.server --transport http --port 8000
{
"mcpServers": {
"instantly": {
"url": "http://localhost:8000/mcp",
"headers": {
"x-instantly-api-key": "<YOUR_INSTANTLY_API_KEY>"
}
}
}
}MCP servers
Egomessss
cakemail
neaj-Corp
joshfreeland