How do I use Instantly MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Instantly MCP Server show me my campaign analytics for the last week" 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.

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.