Instantly MCP server

MCP-сервер, который открывает ваше рабочее пространство Instantly.ai для холодных писем любому ИИ-клиенту. Спросите Claude о проценте ответов за прошлую неделю, загрузите обогащённых лидов в кампанию, разберите входящие в Unibox, поставьте на паузу почтовый ящик, который жжёт репутацию, — 40 инструментов поверх Instantly v2 API.

Смысл проекта — модель безопасности. Каждая операция записи проходит через явный confirm, автономность — это многоуровневая политика с лимитами объёма и списком жёстких блокировок, и всё это реализовано в коде, а не запрашивается в промпте. Агент не сможет обойти лимит разговорами, потому что лимит — это оператор 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

Предпросмотр стоит ноль HTTP-вызовов, поэтому в Instantly ничего не уходит, пока вы сами этого не скажете.

• Транспорт: по умолчанию локальный stdio — без хостинга, публичного URL и токена. Одна переменная окружения переключает его на размещённый HTTP/SSE (Хостинг).

• Аутентификация: ваш ключ Instantly v2, читается из INSTANTLY_API_KEY, никогда не зашивается в код и не логируется.

• Проверено: пути и формы полезной нагрузки проверены по живой v2-справке; каждое место, где реальный API отличается от очевидного предположения, зафиксировано.

• Протестировано: набор тестов полностью замокан и никогда не обращается к живому API.

Быстрый старт

Требуются Python 3.11+ и аккаунт Instantly с доступом к v2 API.

1. Установка

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. Получите API-ключ

В Instantly перейдите в Settings → Integrations → API и создайте v2-ключ. Instantly поддерживает ключи с ограниченными правами — начните с ключа только для чтения, чтобы безопасно опробовать аналитику, а затем расширьте права, когда доверитесь ему.

export INSTANTLY_API_KEY=your_key_here

3. Проверьте запуск

# 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

Никаких HTTP-вызовов не происходит, пока реально не вызван инструмент. Остановите сервер с помощью Ctrl-C.

4. Зарегистрируйте сервер в вашем MCP-клиенте

Добавьте это в конфигурацию клиента, откорректировав абсолютный путь:

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

Если вы устанавливали через venv + pip, а не через uv, укажите в command точку входа venv и уберите args:

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

Где находится этот конфиг (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. Попробуйте

Перезапустите клиент, убедитесь, что инструменты instantly появились, и начните с чтения: «list my Instantly campaigns». Затем попробуйте запись — сначала появится предпросмотр.

Related MCP server: Apollo.io MCP Server

Возможности

40 инструментов. Чтение выполняется свободно; запись разделена на уровни. Полные сигнатуры и уровни — в справочнике инструментов.

Четыре из них жёстко заблокированы — delete_lead, delete_webhook, pause_account, remove_from_blocklist — и никогда не выполняются без confirm=true, на любом уровне автономности, независимо от политики.

Модель безопасности

Помимо уровней: лимиты объёма на вызов и на скользящие 24 часа (лиды, письма, кампании), опциональные списки разрешённых/запрещённых кампаний и дополняемый только в конец audit.log каждой выполненной операции записи с вычищенными секретами. Превышение лимита принудительно включает предпросмотр даже на уровне autonomous. Подробности в разделе Безопасность и автономность.

Хостинг

Локальному stdio не нужен хостинг, и это правильный выбор по умолчанию — здесь нет сетевой поверхности, которую нужно защищать. Размещайте сервер на хостинге, только когда он должен работать при выключенном компьютере, — главным образом для приёма вебхуков Instantly. При работе по HTTP входящая аутентификация обязательна, и сервер закрывается при сбое: без токена, с токеном короче 32 символов или с публичным URL без https он отказывается запускаться. В комплект входят Dockerfile и Render-блюпринт. См. Хостинг.

Документация

Структура репозитория

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

Разработка

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

CI запускается как при каждом push, так и при каждом pull request на Python 3.11, 3.12 и 3.13.

Лицензия

MIT.