Instantly MCP server

Instantly.ai 콜드 이메일 워크스페이스를 AI 클라이언트에서 사용할 수 있게 해주는 MCP 서버입니다. Claude에게 지난주 답장률을 물어보고, 보강된 리드를 캠페인에 로드하고, Unibox를 분류하고, 평판을 떨어뜨리고 있는 사서함을 일시 중지하세요 — Instantly v2 API를 통한 40가지 도구가 제공됩니다.

이 프로젝트의 핵심은 안전 모델입니다. 모든 쓰기 작업은 명시적인 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에 도달하지 않습니다.

• 전송(Transport): 기본값은 로컬 stdio — 호스팅도, 공개 URL도, 토큰도 필요 없습니다. 환경 변수 하나로 호스팅형 HTTP/SSE로 전환됩니다 (호스팅).

• 인증(Auth): INSTANTLY_API_KEY에서 읽어오는 Instantly v2 키를 사용하며, 하드코딩되거나 로그에 기록되지 않습니다.

• 검증(Verified): 실제 v2 레퍼런스와 대조해 경로와 페이로드 형태를 확인했습니다. 실제 API가 예상과 다른 모든 부분은 문서로 기록되어 있습니다.

• 테스트(Tested): 테스트 스위트는 완전히 모킹되어 있으며 실제 API에는 절대 접근하지 않습니다.

빠른 시작

**Python 3.11+**와 v2 API 액세스 권한이 있는 Instantly 계정이 필요합니다.

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는 범위 지정(scoped) 키를 지원합니다. 안전하게 분석을 시도하려면 읽기 전용 키로 시작하고, 신뢰할 수 있게 되면 범위를 넓히세요.

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" }
    }
  }
}

uv 대신 venv + pip로 설치했다면 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 도구가 나타나는지 확인한 다음, 읽기부터 시작하세요: "내 Instantly 캠페인 목록을 보여줘". 그런 다음 쓰기를 시도하면 먼저 미리보기가 표시됩니다.

Related MCP server: Apollo.io MCP Server

할 수 있는 일

도구 40개. 읽기는 자유롭게 실행되고 쓰기는 계층화되어 있습니다. 전체 시그니처와 계층은 도구 레퍼런스에 있습니다.

이 중 4개는 하드 블록되어 있습니다 — delete_lead, delete_webhook, pause_account, remove_from_blocklist — 정책이 무엇이든 모든 자율성 수준에서 confirm=true 없이는 절대 실행되지 않습니다.

안전 모델

계층에 더해: 호출별 및 롤링 24시간 볼륨 상한(리드, 이메일, 캠페인), 선택적 캠페인 허용/거부 목록, 그리고 비밀값이 마스킹된 채 실행된 모든 쓰기를 기록하는 추가 전용(append-only) audit.log가 있습니다. 상한을 초과하면 autonomous에서도 미리보기가 강제됩니다. 자세한 내용은 안전 및 자율성에서 확인하세요.

호스팅

로컬 stdio는 호스팅이 필요 없으며 올바른 기본값입니다. 방어해야 할 네트워크 노출이 없기 때문입니다. 서버가 머신이 꺼져 있는 동안에도 존재해야 할 때만 호스팅하세요. 주로 Instantly 웹훅을 수신하기 위해서입니다. HTTP를 통할 때는 인바운드 인증이 필수이며 서버는 fail-closed로 동작합니다. 토큰이 없거나, 토큰이 32자 미만이거나, https가 아닌 공개 URL이면 시작을 거부합니다. 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는 모든 푸시와 풀 리퀘스트에서 Python 3.11, 3.12, 3.13을 대상으로 실행됩니다.

라이선스

MIT.