☎️ five9-mcp

당신의 Five9 연락 센터를 AI 손안에.

Claude, ChatGPT 또는 모든 MCP 클라이언트를 Five9 클라우드 연락 센터에 연결하는 오픈소스 MCP 서버입니다. Cloudflare Workers에서 의존성 없이 실행됩니다.

빠른 시작 · Claude 연결 · ChatGPT 연결 · 도구 · 아키텍처

AI에게 이렇게 물어보세요:

"지금 누가 통화 중이고, 영업 큐는 얼마나 깊어?" 📊 "복귀 유도 목록용 미리보기 캠페인을 만들고, 영업 스킬을 연결한 다음 시작해." 🛠️ "OUTBOUND_AGED 캠페인을 중단하고 이 리드 3개를 콜백 목록에 추가해." 📞 "새 상담원을 온보딩해: 사용자를 만들고 빌링 스킬을 레벨 2로 배정해." 🧑💼 "555-867-5309가 우리 DNC에 있니? 누가 전화를 걸기 전에 확인해." 🚫 "어제 통화 기록 리포트를 뽑아서 포기율을 요약해." 📈 "전체 IVR을 만들어: 1번은 스케줄, 2번은 청구, 업무 시간 후에는 음성사서함으로." 🧩

내부적으로 이 서버는 Five9의 Configuration(관리자) 및 Statistics(슈퍼바이저) **SOAP 웹 서비스를 사용합니다 — Five9 관리자 화면을 여전히 구동하는 API입니다 — 이를 MCP 스트리머블 HTTP를 통해 깔끔한 JSON 도구로 노출합니다. 직접 작성하여 모양이 만들어진 SOAP 봉투, 약 60줄짜리 XML 파서, npm 패키지 없음. 모든 도구는 라이브 Five9 도메인에서 실행해 검증했습니다.

✨ 내장 웹 UI

배포하면 Worker가 단순한 API 그 이상을 제공합니다:

콘솔은 자격 증명이 올바른지 확인하고, 각 도구가 무엇을 반환하는지 살펴보고, 캠페인을 디버깅하는 가장 빠른 방법입니다 — AI 없이도 가능합니다.

Related MCP server: five9-mcp

🚀 빠른 시작 — 터미널 없이

무료 Cloudflare 계정과 API 액세스가 있는 Five9 사용자가 필요합니다. — Five9 API 전용 사용자를 생성할 때 AI가 수행하길 시키는 범위로만 제한하세요. 개인 관리자 로그인을 재사용하지 마세요.

1 — Cloudflare에 배포 (원클릭, 브라우저에서)

Claireflare에 로그인하고 안내를 따라 클릭하세요 — Workers의 복사본(필요한 KV 네임스페이스 포함)이 만들어지고 https://five9-mcp.you.workers.dev 같은 URL이 제공됩니다.

2 — 설정 마법사 실행 (브라우저에서)

새 서버에서 /setup 을 엽니다. Five9 사용자 이름, 비밀번호, 리전을 입력하세요. 저장하기 전에 Five9에 대해 실시간 검증을 하고, 그다음 액세스 키를 안내합니다(한 번만 표시 — 비밀 관리자에 저장하세요).

3 — AI 연결 (아래 안내 참조), 그 후 "연결을 확인하고 내 캠페인을 나열해." 🎉라고 요청하세요.

git clone https://github.com/ryanshatz/five9-mcp
cd five9-mcp
npx wrangler deploy   # provisions the CONFIG KV namespace on first deploy

그다음 /setup 마법사를 사용하거나 한번에 건너뛰고 자격 증명을 Wrangler 시크릿으로 관리합니다(시크릿은 마법사보다 우선합니다):

npx wrangler secret put FIVE9_USERNAME   # e.g. apiuser@yourdomain
npx wrangler secret put FIVE9_PASSWORD
npx wrangler secret put MCP_AUTH_TOKEN   # a long random string — this is the key to your server

기본값은 wrangler.toml에 있으며 미국 도메인에 적합합니다:

🔌 AI 연결

Claude 연결 (웹 & 데스크톱)

사용자 정의 커넥터는 무료(커넥터 1개), Pro, Max, Team, Enterprise 요금제에서 사용 가능합니다.

1. claude.ai 또는 Claude 데스크톱 앱에서 설정 → 커넥터를 엽니다.

2. 사용자 정의 커넥터 추가를 클릭합니다.

3. 이름을 Five9으로 하고 /mcp 경로를 포함한 서버 URL을 붙여 넣으세요: https://<your-worker>.workers.dev/mcp

4. 추가 클릭 후 연결을 클릭합니다. Claude가 이 서버에 **내장된 OAuth를 자동으로 감지하여 권한 부여 페이지를 엽니다.

5. 🔐 five9-mcp 화면에서 MCP_AUTH_TOKEN 을 액세스 키로 붙여넣고 Authorize 를 클릭합니다.

6. 채팅에서 검색 및 도구(＋) 메뉴를 열고 Five9 커넥터가 켜져 있는지 확인합니다.

Team/Enterprise: 오너가 먼저 조직 설정 → 커넥터에서 커넥터를 추가한 후, 구성원이 자신의 설정에서 연결을 클릭하여 권한을 부여해야 합니다.

ChatGPT 연결

맞춤 MCP 커넥터에는 개발자 모드가 필요합니다 (Plus/Pro; Business/Enterprise에서는 관리자가 맞춤 커넥터를 허용해야 합니다).

1. 웹에서 ChatGPT에 접속한 후 설정 → 앱 및 커넥터 열기(때로는 커넥터로만 표시).

2. 고급 설정에서 개발자 모드를 활성화.

3. 커넥터 페이지로 돌아가 만들기를 클릭.

4. 이름을 Five9로 지정하고, MCP server URL을 https://<your-worker>.workers.dev/mcp로 설정한 다음 OAuth 인증을 선택.

5. 신뢰 프롬프트를 확인하고 저장하기. ChatGPT가 이 서버의 권한 부여 페이지를 엽니다 — MCP_AUTH_TOKEN을 붙여넣고 Authorize 클릭.

6. 새 채팅에서 ＋/ 도구 메뉴를 열고 Five9 커넥터를 활성화(개발자 모드 커넥터는 대화마다 활성화됩니다). ChatGPT는 각 도구 호출을 확인하라고 요청합니다 — dialer를 시작할 수 있는 for 호출에는 말이 되네요. 😄

Claude Code 연결

claude mcp add --transport http five9 https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

Raw(원본) 액세스 키가 베어러 토큰으로 바로 작동합니다 — OAuth 절차 필요 없습니다. Claude 코드 안에서 /mcp를 실행해 확인하세요.

기타 MCP 클라이언트

MCP streamable HTTP를 지원하는 어떤 클라이언트든 작동합니다 — OAuth 절차를 완료하거나 엑세스 키를 베어러 토큰으로 보내세요:

curl -X POST https://<your-worker>.workers.dev/mcp \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_connection","arguments":{}}}'

src/oauth.js는 단일 운영자(배포를 대상으로 설계된 최소한의 OAuth 2.1 인증 서버(메타데이터 검색, 동적 클라이언트 등록, PKCE S256, 리프레시 토큰)를 구현합니다.

• 동의 화면의 "로그인"은 서버의 액세스 키(MCP_AUTH_TOKEN)입니다.

• 모든 것이 상태 비저장입니다 — 클라이언트 ID, 인증 코드, 토큰은 MCP_AUTH_TOKEN으로 서명된 HMAC-SHA256 블롭입니다. KV도, Durable Object도 없습니다.

• 두 인증 경로 모두 동시에 작동합니다: OAuth 발급 토큰과 원시 키를 bearer 자격 증명으로 사용.

• 시크릿을 교체해 한 번에 모두 해지할 수 있습니다: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 도구 모음

도구 총 77개. 🟢 = 읽기 전용(항상 안전) · ✏️ = 쓰기(도메인 변경 — 서버는 AI가 먼저 사용자 확인을 받도록 안내합니다)

69개 SOAP 도구(username/ password) + 8개 CNew Platform REST 도구 (Consumer Key/Secret — OAuth New Platform APIs 참조)

가장 중요한 사용 방법: 콜 흐름을 문단으로 설명하면, AI가 이를 설계하고 채팅에서 Mermaid 다이어그램을 보여준 뒤 작동하는 IVR 스크립트를 배포합니다. 모델은 Five9의 IVR XML을 즉흥적으로 만들지 않습니다. 제한된 JSON 흐름 명세(play / menu / business-hours / skill transfer / voicemail / hangup)를 작성하며, 그래프 검증기가 모든 분기와 참조를 확인하고, 메시지엔 설계자 스타일의 XML을 생성합니다(모듈연결, 프롬프트 인코딩, 필드 순서 모두 실제의 exported scripts에서 파생된 값).

권장 흐름: 먼저 검증 → 렌더링(사람에게 보여주기) → 프롬프트 생성 → 빌드 → 인바운드 캠페인에 첨부. generate_prompt_audio는 Cloudflare Workers AI에서 기본 동작합니다: 외부 TTS 계정, API 키가 필요 없고, 프롬프트 하나 당 센트의 1/100 수준 요금만 기존에 배포한 Cloudflare 계정으로 청구됩니다. ElevenLabs/OpenAI 키 시크릿을 설정해도 동일하게 사용할 수 있고, {tts} 프롬프트(Five9 내장 로봇 음성)는 아무것도 요구하지 않습니다.

이 도구들은 위 도구들이 사용하는 SOAP API가 아닌 Five9의 최신 OAuth 2.0 "New Platform" REST API를 사용합니다. 이들은 API Access Control 자격 증명(Consumer Key/Secret)을 필요로 하며, SOAP 사용자 이름/암호는 사용하지 않습니다 — OAuth New Platform APIs 참조.

🔐 OAuth New Platform APIs

기본 SOAP 도구와 함께, 서버는 Five9의 최신 OAuth 2.0 New Platform REST API도 호출할 수 있습니다 (예: Circles, interactions, prompts, domain metadata). 이들은 SOAP 사용자/암호와 다른 자격 증명을 사용합니다:

• API Access Control Consumer Key 및 Consumer Secret는 Five9 관리자 콘솔 → API Access Control에서 생성합니다(Controlled-Availability 기능). 하나를 생성하려면 security → applications → Create applications 권한이 필요하며, 계정이 Five9 Identity Service로 마이그레이션되어 있어야 합니다(레거시 API/Agent/Supervisor 역할이 있는 사용자는 해당 역할이 제거되기 전까지 마이그레이션에서 제외됩니다).

• 이 항목들을 env/secret 변수로 구성하세요(모두 SOAP 자격 증명과 별개로):

FIVE9_CONSUMER_KEY=...           # "All APIs access" family credential (default)
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109           # your Admin Console domain id
FIVE9_REST_REGION=US             # US | US-ALPHA | CA | EU | IN | UK
# or pin the base URL directly: FIVE9_REST_BASE_URL=https://api.prod.us.five9.net

# Optional second credential for the "Data Tables access" family (its own key):
FIVE9_DT_CONSUMER_KEY=...
FIVE9_DT_CONSUMER_SECRET=...

그런 다음 rest_check_connection을 실행하여 토큰 흐름을 확인하세요. 각 자격 증명이 접근할 수 있는 범위는 해당 API family + scopes로 결정됩니다 — all-apis-access는 말 그대로 모든 서비스에 권한을 부여하지는 않으며, 쓰기 권한은 서비스별로 부여됩니다.

여러 자격 증명 / 패밀리. 각 API Access Control 자격 증명은 하나의 family(Apigee API Product에 매핑됨)에 속하며, 그 family가 키가 호출할 수 있는 서비스를 결정합니다. 서버는 명명된 자격 증명을 지원합니다: default(FIVE9_CONSUMER_KEY/SECRET에서)와 data-tables(FIVE9_DT_CONSUMER_KEY/SECRET에서)입니다. Data Tables 도구들은 data-tables 자격 증명을 자동으로 사용하며, rest_call과 rest_check_connection은 credential 인자를 받아 하나를 선택할 수 있습니다.

참고: Five9의 시작하기 문서는 토큰 엔드포인트를 /v1/auth/token으로 안내하지만, 실제 운영 엔드포인트는 **/oauth2/v1/token**입니다(이 클라이언트가 사용하는 주소).

🎨 운영자 컨텍스트 커스터마이징

src/about.js에는 MCP의 instructions 필드와 about 도구를 통해 연결된 AI에 제공되는 텍스트가 담겨 있습니다: 누가 서버를 운영하는지, 왜 존재하는지, AI가 어떻게 행동해야 하는지(예: "쓰기 작업 전에 확인")를 말이죠. 이 파일을 편집하여 자신의 배포 환경을 설명하세요 — 기본 원본 운영자 컨텍스트가 예시로 포함되어 있습니다.

🏗️ 아키텍처

빌드 단계 없음, 의존성 없음 — src/의 일반 JS 모듈입니다:

src/
├── index.js   # router, CORS, MCP JSON-RPC handler, /setup endpoint
├── five9.js   # SOAP client: envelope builder, ~60-line XML parser, one method per Five9 op
├── tools.js   # MCP tool definitions (JSON Schema) + dispatch
├── oauth.js   # stateless OAuth 2.1 server (single-operator model)
├── config.js  # config resolution: Wrangler secrets > KV (setup wizard)
├── ui.js      # landing page, setup wizard, interactive console
└── about.js   # operator context — edit this for your deployment

요청은 무상태(stateless)입니다: 모든 MCP 호출은 HTTP Basic 인증을 통해 새 Five9 SOAP 교환을 시작합니다. Statistics API는 추가로 setSessionParameters 호출을 요구하는데, get_realtime_stats는 호출할 때마다 이를 수행합니다.

• Five9의 엔드포인트는 JAXB로 생성되며 WSDL 시퀀스에 따라 자식 요소 순서를 검증합니다. 이 서버를 확장한다면 WSDL(https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, HTTP Basic Auth)을 내려받아 <xs:sequence> 순서를 정확히 맞추세요 — basicImportSettings 같은 기본 타입도 포함하며, 이 타입의 요소는 확장 타입 요소보다 앞에 옵니다.

• addToListCsv는 WSDL이 대부분의 항목을 minOccurs="0"으로 표시해도 cleanListBeforeUpdate, crmAddMode, crmUpdateMode, listAddMode를 모두 요구합니다.

• List/CRM 가져오기는 비동기적입니다: 호출은 즉시 가져오기 식별자를 반환하며, 결과는 get_import_result를 폴링하여 확인합니다.

• 연락처 레코드 값은 <values><data>…</data></values>로 래핑된 채 반환됩니다. 여러 응답은 1-요소 배열을 기대하는 곳에서 단일 객체를 반환합니다. five9.js의 toArray()가 이를 정규화합니다.

• 리포트 시간 조건 순서는 <end>가 <start> 앞에 옵니다(JAXB의 알파벳순 정렬).

• IVR xmlDefinition은 비주얼 디자이너의 저장 형식입니다: 모듈은 GUID(ascendants / singleDescendant / branches)로 연결되고, 인라인 TTS 텍스트는 gzip+base64 speakElement 문서로 저장되며, 영업시간 확인은 __DAY__(SUN=1..SAT=7) 및 __TIME__(자정 이후 경과한 분) 시스템 변수를 비교합니다. ivr.js가 이 모든 것을 캡슐화합니다.

• getPrompts는 프롬프 트 ID를 반환하지 않습니다(이름과 타입만). IVR XML 내부의 파일 프롬프트 참조는 id 0과 프롬프트 이름으로 허용된 후 서버 측에서 정규화됩니다. 푸시된 스크립트는 서버가 찍은 domainId를 추가한 채 다시 돌아옵니다.

🛡️ 보안

• Five9 자격 증명은 Cloudflare 계정 안에만 존재합니다 — Worker secrets로 또는(마법사 경로) Workers KV 네임스페이스에 암호화하여 저장됩니다. 어떤 도구도 이를 반환하지 않으며, Wrangler secrets은 항상 KV보다 우선합니다.

• 설정 마법사는 새롭고 미구성된 서버에서만 열립니다 — 배포 직후 실행하세요. 설정이 완료되면 모든 변경에 현재 액세스 키가 필요하며, env로 관리되는 서버는 마법사 변경을 완전히 거부합니다.

• 항상 설정을 완료하십시오(또는 MCP_AUTH_TOKEN을 설정하십시오). 액세스 키 없이 미구성된 서버는 열린 상태로 실행됩니다 — URL을 찾는 사람이라면 누구나 연락처 센터를 조작할 수 있습니다.

• 쓰기 도구(✏️ 참조)는 도메인을 변경합니다. 실제로 AI가 수행하기를 원하는 작업으로 Five9 API 사용자 역할을 범위제한하세요 — Five9 권한이 실제 보안 경계입니다.

• manage_dnc remove와 destroy_list_list는 각기러 주의가 필요합니다. about 지침은 AI가 사용 전에 확인하도록 안내합니다.

• 콘솔은 액세스 키를 브라우저의 localStorage에만 저장하며, 모든 호출은 같은 출처(same-origin)에서 여러분의 Worker로 전달됩니다.

💻 개발

npm run dev      # wrangler dev on http://localhost:8787
npm run deploy   # wrangler deploy

로컬 시크릿은 .dev.vars에 배치합니다(gitignore 대상):

FIVE9_USERNAME=apiuser@yourdomain
FIVE9_PASSWORD=...
MCP_AUTH_TOKEN=dev-local-token

# Optional — external AI voice providers for generate_prompt_audio.
# The default (Workers AI / Deepgram Aura) needs no key at all.
ELEVENLABS_API_KEY=...
OPENAI_API_KEY=...

# Optional — OAuth New Platform REST tools (separate credential; see below)
FIVE9_CONSUMER_KEY=...
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109
FIVE9_REST_REGION=US
FIVE9_DT_CONSUMER_KEY=...        # optional: "Data Tables access" family
FIVE9_DT_CONSUMER_SECRET=...

그런 다음 http://localhost:8787/console을 열고 dev-local-token을 붙여넣은 후 도메인에 대해 호출 도구를 실행하세요 — 또는 위의 curl 스니펫으로 CLI에서 스모크 테스트할 수 있습니다.

🤝 기여

PR 환영합니다! Five9 Config API는 약 180개의 작업을 제공하고 이 서버는 그중 가장 유용한 69개를 래핑합니다 — five9.js + tools.js의 패턴은 확장하기 쉽습니다(먼저 SOAP 참고사항을 읽고 WSDL과의 싸움을 피하세요). 제로 디펜던시 제약을 지켜주세요.

📄 라이선스

MIT · Ryan Shatzkamer 제작