instantly-ai-mcp

Instantly.ai v2 REST API용 MCP 서버로, 문서가 말하는 내용을 신뢰하는 대신 API가 실제로 하는 일을 인코딩합니다. 아래의 모든 특이사항은 변경 로그나 포럼 게시물에서 복사한 것이 아니라 라이브 API에 대해 재현한 것이며, 지속적으로 검증됩니다. npm run verify-gotchas는 요청 시 라이브 계정을 다시 프로빙하여, 여기에 문서화된 내용과 실제 동작이 달라진 주장이 있으면 플래그를 표시합니다(이 표가 기계 검증되는 이유 참조 - 수동 검사이며 CI의 일부가 아닙니다).

특이사항들

이 표가 이 저장소가 존재하는 이유입니다. 이 API를 기반으로 구축된 모든 서버는 결국 이런 특이사항들을 어렵게 다시 발견하게 됩니다. 보통은 잘못된 것처럼 보이는 오류를 보고 깨닫게 됩니다. 2026-08-21에 라이브로 캡처되었습니다. 이 표가 어떻게 정직함을 유지하는지는 이 표가 기계 검증되는 이유를 참고하세요.

흥미로운 행에 대한 참고 사항:

• #3 — 라이브 프로브가 campaign_ids: [id]를 보냈고 5개의 리드를 받았는데, 5개 모두 다른 캠페인에 속해 있었습니다. 이 매개변수는 무시되는 것뿐만 아니라 조용히 아무 효과 없는 필터이며, 단수 campaign 매개변수가 실제로 쿼리 범위를 지정합니다. list_leads는 정확히 이런 이유로 반환된 각 리드의 자체 campaign 필드를 검증하고, 필터를 신뢰하는 대신 경고를 표시합니다.

• #4 — 이 항목은 2026-08-17에 유지됨(HOLDS)으로 기록되었고 2026-08-21에 반박됨(REFUTED)으로 전환되었습니다. ?id=는 이제 단일 캠페인으로 분석을 올바르게 필터링합니다. 이 전환이 이 저장소의 핵심 포인트인 이유는 아래를 참조하세요.

• #5 — 2026-08-17에는 검증 불가(UNVERIFIABLE)였고(테스트할 초안 캠페인이 계정에 없었음), 이후 라이브 통합 테스트 스위트(INSTANTLY_LIVE_TEST=1)에 의해 유지됨(HOLDS)으로 확인되었습니다. 이 테스트는 임시 초안 캠페인을 만들고 필터 없는 /campaigns/analytics가 이를 생략하는지 확인합니다. 위의 유지됨(HOLDS)은 verify-gotchas의 읽기 전용 프로브가 아닌 그 방식으로 검증된 것입니다. 해당 프로브는 계정에 초안 캠페인이 이미 없으면 검증 불가(UNVERIFIABLE)를 반환합니다(절대 만들지 않음). 따라서 초안이 없는 계정에서 실행하면 "재확인 불가"라고 말하는 것이 정상이며, 이 행과 모순되는 것이 아닙니다. list_campaigns는 이런 이유로 GET /campaigns에서 읽습니다. 해당 엔드포인트는 초안을 포함합니다.

• #6, #7, #8은 우연이 아니라 원칙적으로 읽기 전용 프로브로 검증 불가(UNVERIFIABLE)입니다. #6과 #7은 라이브 쓰기(캠페인/웹훅 생성)가 필요하며, 프로브 스크립트는 실제 계정에 대해 의도적으로 그런 작업을 절대 수행하지 않습니다. #8은 요청 시 강제할 수 없는 간헐적 읽기 일관성 문제입니다. 검증 불가(UNVERIFIABLE)는 여기서 실제적이고 정직한 결과입니다 — 아래를 참조하세요.

이 표가 기계 검증되는 이유

수동으로 유지 관리되는 특이사항 목록은 썩습니다. 위의 #4 주장이 그 증거입니다. 2026-08-17에 유지됨(HOLDS)으로 기록되었고, 4일 후인 2026-08-21에 Instantly가 서버 측에서 ?id= 매개변수를 수정한 것으로 보이면서 반박되었습니다. 4일은 긴 꼬리가 아닙니다 — 문서화된 가정 아래에서 문서화되지 않은 API가 얼마나 빨리 움직일 수 있는지를 보여줍니다.

npm run verify-gotchas는 각 주장의 프로브를 라이브 API에 대해 다시 실행하고 5열 표(#, 주장, 검증 결과, 관찰 결과, 마지막 확인 날짜)를 출력합니다. 이는 위의 3열 요약의 상위 집합이며, 라이브 프로브의 원시 증거와 실행 날짜를 포함합니다. 위의 표와 모양이 같지 않습니다. 바이트 단위 일치를 기대하지 마세요.

각 주장은 또한 문서화된 예상 결과(#1–#3 및 #5는 유지됨(HOLDS), #4는 반박됨(REFUTED), #6–#8은 검증 불가(UNVERIFIABLE))를 포함합니다. 이는 현재 문서화된 상태, 즉 이 README가 오늘 말하는 내용입니다. 스크립트는 프로브의 실제 결과가 그 기대치에서 실제로 변경된 경우에만 0이 아닌 종료 코드를 반환하며(예: 문서화된 유지됨(HOLDS)이 반박됨(REFUTED)으로 돌아옴), 정확히 어떤 주장이 어느 방향으로 표류했는지 출력합니다. 이미 문서화된 반박됨(REFUTED) 주장(예: #4)을 재확인하는 것은 표류가 아니며 실행을 실패시키지 않습니다. 새로운 변경만 실패시킵니다.

검증 불가(UNVERIFIABLE)는 스크립트가 정직하게 보고하는 실제 결과이며, 은폐하는 실패가 아닙니다. 어느 방향으로도 표류로 간주되지 않습니다. 일부 주장은 안전하고 읽기 전용이며 비파괴적인 프로브로는 진정으로 확인할 수 없습니다(위 #6–#8 참조). 스크립트는 추측하거나 조용히 건너뛰는 대신 그렇게 말합니다. #5가 가장 명확한 사례입니다. 문서화된 유지됨(HOLDS)은 이 프로브가 아닌 라이브 통합 테스트에서 나온 것이므로, 프로브가 검증 불가(UNVERIFIABLE)(현재 초안 캠페인이 없음)로 돌아오는 것은 "재확인 불가"로 보고되며 실패가 아닙니다.

INSTANTLY_API_KEY=your-key npm run verify-gotchas

verify-gotchas는 CI에 연결되지 않고 수동으로 실행됩니다. .github/workflows/ci.yml을 확인하세요. build, typecheck, test만 실행합니다. 이는 실수나 간과가 아니라 의도적인 선택입니다. CI에는 라이브 API 키가 없습니다(스크립트는 키 없이도 깔끔하게 자체 건너뛰며, 메시지를 출력하고 0으로 종료합니다 — scripts/verify-gotchas.ts 상단 참고 — 따라서 어차피 CI에서는 조용한 no-op이 됩니다). 이 스크립트는 실제 계정의 읽기 엔드포인트를 건드리기 위해 존재하며, 저장소의 CI가 무인으로 수행할 일이 아닙니다. 새로 읽고 싶을 때 로컬에서 자신의 계정에 대해 실행하세요.

설치

{
  "mcpServers": {
    "instantly": {
      "command": "npx",
      "args": ["-y", "instantly-ai-mcp"],
      "env": { "INSTANTLY_API_KEY": "your-v2-api-key" }
    }
  }
}

Instantly 대시보드의 설정 → 통합 → API에서 v2 API 키를 받으세요. Node 20+가 필요합니다.

안전 모델

도구는 환경 변수로 게이트되는 세 가지 계층으로 그룹화됩니다. 비활성화된 계층은 MCP 서버에 전혀 등록되지 않습니다 — 이 서버와 대화하는 모델은 허용되지 않은 도구를 볼 수도, 시도할 수도 없습니다. 영리한 프롬프트로 우회할 수 있는 런타임 권한 검사가 아닙니다.

위험 계층은 의도적으로 두 플래그 모두 필요합니다. 일상적인 쓰기(리드 업로드, 주소 차단 목록)를 켜도 캠페인 활성화, 전송, 삭제가 조용히 활성화되지 않습니다. 이 네 가지 도구는 추가로 MCP의 destructiveHint: true 주석을 포함합니다. 이는 계층이 활성화된 경우에도 호환 클라이언트가 (예: 사용자에게 확인을 요청하는 방식으로) 조치할 수 있는 힌트입니다. 이는 클라이언트가 적용하는 동작이며, 이 서버가 보장하는 것은 아닙니다. 힌트를 무시하는 클라이언트는 추가 확인 단계 없이 도구를 호출합니다.

도구

읽기 (항상 등록됨)

• list_campaigns — 초안을 포함한 모든 캠페인을 숫자 상태로 디코딩하여 나열.

• list_accounts — 연결된 발신 사서함을 워밍업 점수, 상태, 일일 한도와 함께 나열.

• campaign_state — 하나의 캠페인 상태를 세 개의 독립적인 엔드포인트에서 교차 확인하고, 어느 하나를 선택하는 대신 불일치를 보고. 리드 목록 읽기는 페이지 범위(한 페이지, 한도 100)이며, 전체 페이지는 Instantly 불일치로 보고하지 않고 페이지 제한으로 명확히 보고됩니다.

• list_leads — 캠페인의 리드를 단수 campaign 매개변수로 필터링하여 나열하며, 반환된 리드의 자체 캠페인 필드가 일치하지 않으면 경고를 표시합니다. 한 페이지(기본 한도 100)를 읽습니다. 결과의 pageLimited는 그 너머에 더 많은 리드가 있을 수 있음을 알려줍니다.

• find_lead — search 매개변수로 이메일로 리드 하나를 찾습니다. list_leads가 잘못 보일 때 올바른 두 번째 의견입니다. search는 퍼지(fuzzy)이므로, 행은 자체 주소가 요청한 주소와 일치할 때만 반환됩니다. 근사 일치는 리드로 보고되지 않고 null로 보고됩니다.

• list_replies — 인용된 스레드/서명이 제거되고 관심 상태가 디코딩된 수신 답장을 나열합니다.

쓰기 (INSTANTLY_MCP_WRITE=1)

• add_leads — 두 개의 독립적인 읽기 경로를 통해 diff(개수가 아닌)로 검증하여 캠페인에 리드를 업로드합니다. 100개 이상의 리드가 있는 캠페인의 경우 검증 읽기도 페이지 제한이 적용됩니다. 결과의 pageLimited 및 note 필드가 이를 알려줍니다.

• blocklist_address — 전체 이메일 주소 하나를 차단 목록에 추가합니다. 구조적으로 도메인만 있는 것은 거부합니다.

• update_lead — 리드의 필드를 패치합니다.

• create_campaign — 초안으로 캠페인을 생성합니다(전송하지 않음). 네트워크 호출 전에 시간대 enum을 검증합니다.

• create_webhook — 웹훅 구독을 생성합니다. 네트워크 호출 전에 이벤트 유형 enum을 검증합니다.

위험 (INSTANTLY_MCP_WRITE=1 및 INSTANTLY_MCP_ALLOW_DANGEROUS=1)

• set_campaign_status — 캠페인을 활성화하거나 일시 중지합니다. 활성화는 즉시 실제 이메일 전송을 시작합니다.

• send_reply — 리드에게 실제로 되돌릴 수 없는 답장을 보냅니다. 일반 텍스트는 html 본문에 원시로 붙여넣는 대신 HTML 이스케이프되고 줄바꿈됩니다. 직접 html을 전달하여 재정의할 수 있습니다.

• delete_lead — 리드를 영구 삭제합니다.

• delete_campaign — 캠페인과 그 기록을 영구 삭제합니다.

알려진 제한 사항

list_replies는 각 답장에서 인용된 원본 스레드와 서명을 제거합니다(src/reply-text.ts). 의도적으로 보수적입니다. 모호한 입력에서는 실제 텍스트를 삭제할 위험보다는 인용문을 남깁니다. 따라서 아래의 모든 나머지 가장자리 사례는 안전한 방향으로 실패합니다. 인용된 스레드가 반환된 텍스트에 남아 노이즈가 되지만, 문장이 삭제되어 데이터가 손실되는 일은 없습니다.

• 요일만 언급하는 귀속, 예: On Tuesday ... wrote:는 스트리퍼가 요구하는 날짜/시간 신호를 포함하지 않으므로 제거되지 않습니다.

• 주소가 없는 소문자 발신자를 언급하는 귀속, 예: ... at 8:22 AM, john wrote:는 발신자 형태 검사(실제 발신자는 주소, 대문자 이름 또는 대명사로 읽힘)를 통과하지 못하므로 제거되지 않습니다.

• 전체가 서명인 본문(첫 번째 비어 있지 않은 줄에 -- 가 있고 그 앞에 아무것도 없는 경우)은 비워지지 않고 구분 기호를 포함한 전체가 반환됩니다.

빌드 중 발견된 두 가지 과도한 스트리핑은 실제 잠재 고객 텍스트를 삭제했습니다. -- 로 시작하는 본문은 완전히 비워졌고, On May 5 reasons you wrote: ... 형태의 산문은 인용 스레드 마커로 오인되어 잘렸습니다. 둘 다 첫 릴리스 전에 수정되었으며 오프라인 스위트(test/reply-text.test.ts, "Fix round 4")로 다루어집니다.

여전히 답장의 원본, 스트리핑되지 않은 body.text를 반환하는 도구는 없습니다. list_replies의 답장이 수상할 정도로 짧다면, 잠재 고객이 실제로 말한 것보다 적게 말했다고 결론 내리기 전에 Instantly 대시보드에서 확인하세요.

기존 사례

기존 패키지인 instantly-mcp(bcharleson 작성)는 비슷한 영역을 다루며 마지막 게시는 2025-06-17입니다. 2026-08-21 기준으로 npm latest 태그는 1.0.5를 가리키는 반면 next 태그는 3.0.5-1을 가리킵니다. 따라서 일반적인 npx instantly-mcp는 패키지 자체의 최신 게시 코드보다 훨씬 오래된 빌드를 설치합니다(dist 태그는 이 글이 작성된 후 변경될 수 있습니다. 현재 상태는 npm view instantly-mcp dist-tags로 다시 확인하세요). 이것은 비방이 아니라 사실로서 언급된 것입니다. instantly-ai-mcp는 포크나 대체재가 아니라 독립적이고 무관한 프로젝트이며 초점이 다릅니다(주의사항 표와 자체 검증).

테스트

픽스처 스위트(npm test)는 모의(mock) 클라이언트를 대상으로 완전히 오프라인에서 실행되며 API 키가 필요 없습니다. 별도의 라이브 통합 스위트는 INSTANTLY_LIVE_TEST=1(및 실제 INSTANTLY_API_KEY)을 조건으로 실제 API를 실행합니다. 하지만 이 스위트는 오직 자체 임시 초안 캠페인(zz-instantly-ai-mcp-throwaway-<timestamp> 이름)만 생성, 읽기, 삭제하며 기존 캠페인이나 리드를 건드리지 않고, 어떤 것도 활성화하거나 전송하지 않습니다. 플래그나 키가 없으면 자체적으로 건너뛰며, CI에서는 항상 그렇습니다.

라이선스

MIT