Instantly MCP server

Un servidor MCP que pone tu espacio de trabajo de email en frío de Instantly.ai ante un cliente de IA. Pregunta a Claude por la tasa de respuesta de la semana pasada, carga leads enriquecidos en una campaña, haz triaje de la Unibox, pausa un buzón que está quemando su reputación: 40 herramientas sobre la API v2 de Instantly.

El propósito del proyecto es el modelo de seguridad. Cada escritura requiere una confirm explícita, la autonomía es una política por niveles con límites de volumen y una lista de bloqueo estricto, y todo ello se aplica en código, no se pide en un prompt. Un agente no puede saltarse un límite con argucias, porque el límite es una sentencia if.

You:    "Launch the Design Partners campaign."
Claude: → launch_campaign(campaign_id="camp-1")
        ← "Would LAUNCH (activate) campaign camp-1 — it will start sending.
           AUTONOMY_LEVEL=manual — every write needs confirm=true.
           Re-call with confirm=true to execute."
        This will start sending from your mailboxes. Confirm?
You:    "Yes."
Claude: → launch_campaign(campaign_id="camp-1", confirm=true)   ← now it runs

La previsualización cuesta cero llamadas HTTP, así que nada llega a Instantly hasta que tú lo decidas.

• Transporte: stdio local por defecto: sin alojamiento, sin URL pública, sin token. Una variable de entorno lo cambia a HTTP/SSE alojado (Alojamiento).

• Autenticación: tu clave de Instantly v2, leída de INSTANTLY_API_KEY, nunca incrustada en el código y nunca registrada.

• Verificado: las rutas y las estructuras de los payloads se comprueban contra la referencia v2 en vivo; cada punto en el que la API real difiere de la suposición obvia está documentado.

• Probado: la suite está completamente simulada y nunca toca la API real.

Inicio rápido

Requiere Python 3.11+ y una cuenta de Instantly con acceso a la API v2.

1. Instala

git clone https://github.com/katekruger/instantlymcp.git
cd instantlymcp

# Option A — uv (preferred)
uv sync

# Option B — venv + pip
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Obtén una clave de API

En Instantly, ve a Settings → Integrations → API y crea una clave v2. Instantly admite claves con ámbito: empieza con una clave de solo lectura para probar la analítica con seguridad y, cuando confíes en ella, amplía los ámbitos.

export INSTANTLY_API_KEY=your_key_here

3. Comprueba que arranca

# Fails cleanly if the key is unset:
unset INSTANTLY_API_KEY
instantly-mcp        # -> "ERROR: INSTANTLY_API_KEY is not set", exit 1

# Starts (stdio server waits on stdin) with any non-empty key:
INSTANTLY_API_KEY=dummy instantly-mcp

No se realiza ninguna llamada HTTP hasta que se invoca una herramienta. Pulsa Ctrl-C para detenerlo.

4. Regístralo en tu cliente MCP

Añade esto a la configuración de tu cliente, ajustando la ruta absoluta:

{
  "mcpServers": {
    "instantly": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/instantlymcp", "run", "instantly-mcp"],
      "env": { "INSTANTLY_API_KEY": "your_key_here" }
    }
  }
}

Si instalaste con venv + pip en lugar de uv, apunta command al punto de entrada del venv y elimina args:

{
  "mcpServers": {
    "instantly": {
      "command": "/absolute/path/to/instantlymcp/.venv/bin/instantly-mcp",
      "env": { "INSTANTLY_API_KEY": "your_key_here" }
    }
  }
}

Dónde se encuentra esa configuración (macOS):

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Code: claude mcp add instantly -e INSTANTLY_API_KEY=your_key_here -- uv --directory /absolute/path/to/instantlymcp run instantly-mcp

5. Pruébalo

Reinicia el cliente, confirma que aparecen las herramientas de instantly y empieza con una lectura: "list my Instantly campaigns". Después prueba una escritura — primero verás una previsualización.

Related MCP server: Apollo.io MCP Server

Qué puede hacer

40 herramientas. Las lecturas se ejecutan libremente; las escrituras están por niveles. Firmas completas y niveles en la referencia de herramientas.

Cuatro de ellas están bloqueadas por completo — delete_lead, delete_webhook, pause_account, remove_from_blocklist — y nunca se ejecutan sin confirm=true, en ningún nivel de autonomía, diga lo que diga la política.

El modelo de seguridad

Además de los niveles: límites de volumen por llamada y en ventana móvil de 24 horas (leads, emails, campañas), listas opcionales de campañas permitidas y denegadas, y un audit.log de solo añadidura con cada escritura ejecutada y los secretos redactados. Superar un límite fuerza una previsualización incluso en autonomous. Detalles en Seguridad y autonomía.

Alojamiento

El stdio local no necesita alojamiento y es el valor por defecto adecuado: no hay exposición de red que defender. Alójalo solo cuando el servidor deba existir mientras tu máquina esté apagada, principalmente para recibir webhooks de Instantly. Por HTTP, la autenticación entrante es obligatoria y el servidor falla en modo cerrado: sin token, con un token de menos de 32 caracteres o con una URL pública que no sea https, se niega a arrancar. Se incluyen un Dockerfile y un blueprint de Render. Ver Alojamiento.

Documentación

Estructura del repositorio

src/instantly_mcp/
  server.py      MCP server: the 40 tool definitions, login route, transport selection
  client.py      Instantly v2 API client (httpx) — all HTTP lives here
  models.py      Pydantic input models and normalizers
  policy.py      Risk tiers, autonomy levels, volume caps, audit log
  auth.py        Inbound bearer-token auth for HTTP transports; fails closed
  oauth.py       Single-user OAuth authorization server for MCP clients
  formatting.py  Compact, LLM-friendly summaries of raw API responses
tests/           Fully mocked — never hits the live API
docs/            The pages listed above
Dockerfile       Container image for hosted deployment (non-root, reads $PORT)
render.yaml      Render blueprint; secrets are prompted, never committed
.env.example     Annotated template for every supported variable

Desarrollo

pytest -q                 # all mocked, no network, no API key needed
ruff check src tests      # lint

La CI se ejecuta tanto en cada push como en cada pull request contra Python 3.11, 3.12 y 3.13.

Licencia

MIT.