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)

Campaigns (8 tools)

Leads (12 tools)

Emails (6 tools)

Analytics (3 tools)

Background Jobs (2 tools)

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

API Reference

For detailed API documentation, see: Instantly V2 API Docs

License

MIT License

Contributing

Contributions welcome! Please open an issue or PR.