The Instantly MCP Server enables AI assistants to comprehensively manage Instantly.ai's email campaigns, accounts, leads, and analytics through seamless API integration.
Core Capabilities:
Campaign Management: Create campaigns with intelligent three-stage workflows, update details and status, activate campaigns, and retrieve complete campaign data with pagination
Account Management: List and update sending accounts, monitor warmup analytics, validate account eligibility, and manage daily limits and settings
Lead Management: Create, update, filter, and organize leads across campaigns and lists with comprehensive pagination support
Analytics & Reporting: Track campaign performance, get overview analytics, and monitor warmup progress for sending accounts
Email Operations: Reply to existing emails, list email history with filtering, and verify email addresses for deliverability
Administrative Tools: Manage API keys, check premium feature availability, and validate account permissions
Flexible Deployment: Support for both local (stdio) and remote (HTTP) deployment with robust authentication options
The server provides complete dataset retrieval through automatic pagination and offers premium features like email verification based on your Instantly.ai plan.
Enables connection to Gmail accounts through the Instantly API, supporting email campaign management and deliverability monitoring through IMAP/SMTP authentication.
Provides integration with Google-based email accounts for managing email campaigns, monitoring account health, and handling email verification through the Instantly platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Instantly MCP Server show me my active campaigns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A lightweight, robust Model Context Protocol (MCP) server for the Instantly.ai V2 API, built with FastMCP.
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
Related MCP server: Freshdesk MCP Server
# 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-dotenvSet your Instantly API key:
export INSTANTLY_API_KEY="your-api-key-here"Or create a .env file:
INSTANTLY_API_KEY=your-api-key-here# 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.serverTool | Description |
| List email accounts with filtering |
| Get account details and warmup status |
| Create account with IMAP/SMTP credentials |
| Update account settings |
| Pause, resume, warmup control, test vitals |
| ⚠️ Permanently delete account |
Tool | Description |
| Create email campaign (two-step process) |
| List campaigns with pagination |
| Get campaign details and sequences |
| Update campaign settings |
| Start campaign sending |
| Stop campaign sending |
| ⚠️ Permanently delete campaign |
| Find campaigns a contact is enrolled in |
Tool | Description |
| List leads with filtering |
| Get lead details |
| Create single lead |
| Update lead (⚠️ custom_variables replaces all) |
| List lead lists |
| Create lead list |
| Update lead list |
| Get email verification stats |
| Bulk add up to 1,000 leads |
| ⚠️ Permanently delete lead |
| ⚠️ Permanently delete lead list |
| Move/copy leads between campaigns/lists |
Tool | Description |
| List emails with filtering |
| Get email details |
| 🚨 Send real email reply |
| Count unread inbox emails |
| Verify email deliverability |
| Mark email thread as read |
Tool | Description |
| Campaign metrics (opens, clicks, replies) |
| Day-by-day performance |
| Account warmup metrics |
Tool | Description |
| List async background jobs with pagination |
| Get details of a specific background job |
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_KEYURL: https://your-server.com/mcp
Header: Authorization: YOUR_API_KEYNote: Bearer token prefix is optional
URL: https://your-server.com/mcp
Header: x-instantly-api-key: YOUR_API_KEYexport 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"
}
}
}
}Add to ~/.cursor/mcp.json:
{
"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 fileAspect | TypeScript | Python FastMCP |
Lines of Code | ~5,000+ | ~1,500 |
Tool Registration | Manual handlers |
|
Input Validation | Zod schemas | Pydantic (auto) |
Error Messages | Manual | Auto from Pydantic |
HTTP Server | Custom transport | Built-in |
Context Window | Larger schemas | Smaller, cleaner |
For detailed API documentation, see: Instantly V2 API Docs
MIT License
Contributions welcome! Please open an issue or PR.
Check which premium features are available with your current Instantly plan and API key permissions.
Inputs: no named parameters.
Create a new email campaign with bulletproof three-stage workflow ensuring 100% success rate. Handles both simple requests ("create a campaign") and complex detailed specifications seamlessly.
INTELLIGENT WORKFLOW:
Simple Usage: Just provide basic info (name, subject, body) - tool automatically handles prerequisites
Advanced Usage: Specify all parameters for immediate creation
Guided Mode: Use stage parameter for step-by-step control
THREE-STAGE PROCESS:
Prerequisite Check (stage: "prerequisite_check"): Validates accounts and collects missing required fields
Campaign Preview (stage: "preview"): Shows complete configuration for user confirmation
Validated Creation (stage: "create"): Creates campaign with fully validated parameters
AUTO-STAGE DETECTION: Tool automatically determines appropriate stage based on provided parameters for seamless user experience.
EXAMPLE USAGE:
// Simple: Tool handles everything
create_campaign {"name": "My Campaign", "subject": "Hello", "body": "Hi there"}
// Advanced: Full specification
create_campaign {
"name": "My Campaign",
"subject": "Hello {{firstName}}",
"body": "Hi {{firstName}},\n\nGreat to connect!",
"email_list": ["verified@domain.com"],
"daily_limit": 50
}Inputs: body, confirm_creation, continue_thread, daily_limit, +20 more.
Create a new lead
Inputs: email (required), companyName, custom_fields, firstName, +3 more.
Create a new lead list
Inputs: name (required), description.
Get detailed information about a specific account including warmup status, SMTP settings, and eligibility for campaigns.
Inputs: email (required).
Get details of a specific campaign
Inputs: campaign_id (required).
Get analytics for campaigns
Inputs: campaign_id, end_date, start_date.
Get analytics overview for all campaigns
Inputs: end_date, start_date.
Get a specific email by ID
Inputs: email_id (required).
Get warmup analytics for one or more accounts. API REQUIREMENT: The Instantly API expects an array of email addresses, even for a single account.
Inputs: emails (required), end_date, start_date.
List all sending accounts in the workspace. PREREQUISITE FOR CAMPAIGN CREATION: You MUST call this tool first before creating any campaigns to obtain valid email addresses for the email_list parameter. The returned accounts are the only valid sending addresses that can be used in campaigns.
CRITICAL FOR SUCCESS: Campaign creation will fail if you use email addresses that are not returned by this endpoint. Always use the exact email addresses from this response.
COMPLETE PAGINATION: To get ALL accounts, use one of these approaches:
Set limit=100 or higher (automatically triggers complete pagination)
Set get_all=true (forces complete pagination)
Use limit="all" (string triggers complete pagination)
PAGINATION ALGORITHM: When requesting all accounts, the tool will automatically:
Start with limit=100 per page
Continue fetching until next_starting_after is null or empty results
Report progress: "Retrieved 100... 200... 304 total accounts"
Return complete dataset with validation
ACCOUNT STATUS: Look for accounts with status=1, setup_pending=false, warmup_status=1 for campaign eligibility.
Inputs: get_all, limit, starting_after.
List all API keys
Inputs: no named parameters.
List campaigns with optional filters and complete pagination support. COMPLETE PAGINATION: To get ALL campaigns, use one of these approaches:
Set limit=100 or higher (automatically triggers complete pagination)
Set get_all=true (forces complete pagination)
Use limit="all" (string triggers complete pagination)
PAGINATION ALGORITHM: When requesting all campaigns, the tool will automatically:
Start with limit=100 per page
Continue fetching until next_starting_after is null or empty results
Report progress: "Retrieved 100... 200... 304 total campaigns"
Return summarized data to prevent size limits
Use get_campaign for full details of specific campaigns
FILTERS: search and status filters work with both single-page and complete pagination modes.
Inputs: get_all, limit, search, starting_after, +1 more.
List emails with filters and pagination
Inputs: account_id, campaign_id, limit, starting_after.
List all lead lists with pagination
Inputs: limit, starting_after.
List leads with filters and pagination
Inputs: campaign_id, limit, list_id, starting_after, +1 more.
Reply to an existing email. IMPORTANT: This can only be used to reply to existing emails, not to send new emails. You must provide the ID of an existing email to reply to. Use campaigns for sending new emails.
Inputs: body (required), eaccount (required), reply_to_uuid (required), subject (required), +2 more.
Update a sending account
Inputs: email (required), daily_limit, warmup_enabled.
Update an existing campaign
Inputs: campaign_id (required), name, status.
Update a lead
Inputs: lead_id (required), company, custom_fields, first_name, +1 more.
Validate which accounts are eligible for campaign creation. This tool helps debug campaign creation issues by showing the status of all accounts and which ones meet the requirements for sending campaigns.
Inputs: email_list.
Verify if an email address is valid. IMPORTANT: This feature may require a premium Instantly plan or specific API permissions. If you receive a 403 Forbidden error, check: 1) Your Instantly plan includes email verification, 2) Your API key has the required scopes, 3) Contact Instantly support to confirm feature availability.
Inputs: email (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 22 tools
Most tools have distinct purposes targeting specific resources like campaigns, leads, accounts, or emails, with clear boundaries. However, some potential confusion exists between get_campaign_analytics and get_campaign_analytics_overview, as both relate to campaign analytics but differ in scope, which could lead to misselection without careful reading of descriptions.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_campaign, list_accounts, update_lead, and get_campaign_analytics. This predictability makes it easy for agents to understand and navigate the toolset without ambiguity in naming conventions.
With 22 tools, the count is borderline high for an email marketing server, potentially feeling heavy and overwhelming. While it covers a broad domain, some tools might be redundant or overly specialized, making the set less streamlined than ideal for typical agent workflows.
The toolset provides comprehensive CRUD and lifecycle coverage for campaigns, leads, accounts, and emails, including creation, listing, updating, and analytics. It also includes specialized tools like validate_campaign_accounts and reply_to_email, ensuring no obvious gaps for the email marketing domain and supporting robust agent operations.
Manage contacts, campaigns, senders, and deliverability via SuperSend API
Read LinkedIn outreach campaigns, contacts and replies, and manage campaign leads and targeting.
LinkedIn and email outreach: campaigns, unified inbox, leads, analytics and reports.
Send email, check deliverability, set up domains, and run templates, contacts and campaigns.
