☎️ 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 도구로 노출합니다. 직접 작성한 봉투(envelope), 약 60줄짜리 XML 파서, npm 패키지 없음. 모든 도구는 실제 Five9 도메인에서 테스트되었습니다.

✨ 내장 웹 UI

배포하면 Worker가 API 이상의 것을 제공합니다:

콘솔은 자격 증명을 빠르게 검증하고, 각 도구가 무엇을 반환하는지 탐색하거나, 캠페인을 디버깅하는 가장 빠른 방법입니다 — AI가 필요 없습니다.

Related MCP server: five9-mcp

🚀 빠른 시작 — 터미널 필요 없음

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

1 — Cloudflare에 배포 (브라우저에서 한 번의 클릭)

Cloudflare에 로그인하고 클릭만 하면 됩니다 — 이 Worker의 사본(필요한 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 연결 (웹 및 데스크톱)

커스텀 커넥터는 Free(커넥터 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을 액세스 키로 붙여넣고 승인을 클릭합니다.

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

Team/Enterprise: 소유자가 먼저 조직 설정 → 커넥터에서 커넥터를 추가합니다. 그러면 구성원이 자신의 설정에서 연결을 클릭하여 승인합니다.

ChatGPT 연결

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

1. 웹의 ChatGPT에서 설정 → 앱 및 커넥터(때로는 커넥터로만 표시됨)를 엽니다.

2. 고급 설정에서 개발자 모드를 켭니다.

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

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

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

6. 새 채팅에서 ＋ / 도구 메뉴를 열고 Five9 커넥터를 활성화합니다(개발자 모드 커넥터는 대화별로 활성화됩니다). ChatGPT가 각 도구 호출을 확인하도록 요청합니다 — 발신기를 시작할 수 있는 작업에는 합리적인 기능입니다. 😄

Claude Code 연결

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

원시 액세스 키는 OAuth 절차 없이 베어러 토큰으로 직접 작동합니다. Claude Code에서 /mcp를 실행하여 확인하세요.

기타 모든 MCP 클라이언트

MCP 스트리밍 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 Objects도 없습니다.

• 두 인증 경로가 동시에 작동합니다: OAuth에서 발급된 토큰 및 베어러 자격 증명으로서의 원시 키.

• 시크릿을 교체하여 한 번에 모두 취소: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 도구 상자

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

69개 SOAP 도구(사용자 이름/비밀번호) + 8개 OAuth New Platform REST 도구(Consumer Key/Secret — OAuth New Platform API 참조).

핵심 기능: 통화 흐름을 한 문단으로 설명하면 AI가 설계하고, 채팅에서 Mermaid 다이어그램을 보여주며, 작동하는 IVR 스크립트를 배포합니다. 모델은 Five9의 IVR XML을 임의로 생성하지 않습니다: 제한된 JSON 흐름 사양(재생 / 메뉴 / 영업 시간 / 스킬 전환 / 음성사서함 / 종료)을 채우고, 그래프 검증기가 모든 분기와 참조를 확인하며, 결정적 코드가 디자이너 형식의 XML을 생성합니다(모듈 연결, 프롬프트 인코딩, 필드 순서는 모두 실제 내보낸 스크립트에서 파생됨).

권장 흐름: 검증 → 렌더링(사람에게 보여주기!) → 프롬프트 생성 → 빌드 → 인바운드 캠페인에 연결. generate_prompt_audio는 기본 제공되는 Cloudflare Workers AI에서 실행됩니다: 외부 TTS 계정도, API 키도 없으며, 프롬프트당 1센트 미만의 비용이 이미 배포한 Cloudflare 계정에 청구됩니다. 키 시크릿을 설정하면 ElevenLabs/OpenAI도 작동하며, {tts} 프롬프트(Five9 내장 로봇 음성)는 아무것도 필요 없습니다.

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

🔐 OAuth New Platform APIs

SOAP 도구들과 함께 MCP 서버는 Five9의 최신 OAuth 2.0 New Platform REST API(예: Circles, interactions, prompts, 도메인 메타데이터)를 호출할 수 있습니다. 이들은 SOAP 사용자 이름/비밀번호와 다른 자격 증명을 사용합니다.

• API Access Control Consumer Key 및 Consumer Secret* — Five9 Admin Console → 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 자격 증명은 하나의 패밀리(Apigee API Product에 매핑됨)에 속하며, 그 패밀리가 키가 호출할 수 있는 서비스를 결정합니다. 서버는 명명된 자격 증명(named credentials) 을 지원합니다: 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 인증)을 받아 <xs:sequence> 순서를 정확히 맞추세요. basicImportSettings 같은 기본 타입도 포함하며, 그 요소들은 확장 타입의 요소 앞에 옵니다.

• addToListCsv는 WSDL이 대부분 minOccurs="0"으로 표시함에도 cleanListBeforeUpdate, crmAddMode, crmUpdateMode, listAddMode를 요구합니다.

• List/CRM 가져오기는 비동기적입니다. 호출은 즉시 가져오기 식별자를 반환하며, 결과를 얻으려면 get_import_result를 폴링하세요.

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

• 보고서 시간 조건 순서는 <start> 앞에 <end>가 옵니다(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가 추가된 채 왕복(round-trip)합니다.

🛡️ 보안

• Five9 자격 증명은 Cloudflare 계정에만 저장됩니다. Worker 비밀값으로, 또는(마법사 경로) Workers KV 네임스페이스에 저장되며 저장 시 암호화됩니다. 어떤 도구도 이 값을 반환하지 않으며, Wrangler 비밀값은 항상 KV를 덮어씁니다.

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

• 항상 설정을 완료하세요(또는 MCP_AUTH_TOKEN을 설정하세요). 액세스 키 없이 구성되지 않은 서버는 열린 상태로 실행됩니다 — URL을 찾는 사람 누구나 컨택 센터를 조작할 수 있습니다.

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

• manage_dnc remove와 delete_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 제작