☎️ five9-mcp

당신의 Five9 컨택센터를 AI의 손에.

오픈소스 MCP 서버로, Claude, ChatGPT 또는 모든 MCP 클라이언트를 Five9 클라우드 컨택센터에 연결합니다 — 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 도구로 노출합니다. 수제 봉투, 약 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 APIs 참조).

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

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

이 도구들은 Five9의 최신 OAuth 2.0 "신규 플랫폼" REST API를 사용하며, 위 도구들이 사용하는 SOAP API가 아닙니다. 이를 사용하려면 SOAP 사용자 이름/비밀번호가 아닌 API 액세스 제어 자격 증명(Consumer Key/Secret)이 필요합니다. 자세한 내용은 OAuth 신규 플랫폼 API를 참조하세요.

🔐 OAuth 신규 플랫폼 API

SOAP 도구와 함께, 서버는 Five9의 최신 OAuth 2.0 신규 플랫폼 REST API(예: 서클, 상호작용, 프롬프트, 도메인 메타데이터)를 호출할 수 있습니다. 이 API는 SOAP 사용자 이름/비밀번호와 다른 자격 증명을 사용합니다.

• API 액세스 제어 소비자 키와 소비자 비밀번호는 Five9 관리 콘솔 → API 액세스 제어(제한적 가용성 기능)에서 생성됩니다. 생성하려면 security → applications → Create applications 권한이 필요하며, 계정은 Five9 Identity Service로 마이그레이션되어야 합니다(레거시 API/에이전트/감독자 역할이 있는 사용자는 해당 역할이 제거될 때까지 마이그레이션에서 제외됨).

• 이를 환경 변수/비밀 변수로 구성합니다(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 제품군 + 범위에 의해 결정됩니다. all-apis-access가 말 그대로 모든 서비스에 대한 접근을 부여하는 것은 아니며, 쓰기 접근은 서비스별로 다릅니다.

여러 자격 증명 / 제품군. 각 API 액세스 제어 자격 증명은 하나의 제품군(Apigee API 제품에 매핑됨)에 속하며, 해당 제품군이 키가 호출할 수 있는 서비스를 결정합니다. 서버는 명명된 자격 증명을 지원합니다: 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

요청은 상태 비저장입니다: 모든 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가 필요합니다.

• 목록/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__(일=1..토=7) 및 __TIME__(자정 이후 분) 시스템 변수를 비교합니다. ivr.js가 이 모든 것을 캡슐화합니다.

• getPrompts는 프롬프트 ID를 반환하지 않습니다(이름 + 유형만). IVR XML 내부의 파일 프롬프트 참조는 id 0 + 프롬프트 이름으로 허용되며 서버 측에서 정규화됩니다. 푸시된 스크립트는 서버에서 스탬프된 domainId가 추가되어 왕복합니다.

🛡️ 보안

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

• 설정 마법사는 새롭고 구성되지 않은 서버에서만 열립니다 — 배포 직후 실행하세요. 일단 구성되면 변경하려면 현재 액세스 키가 필요하며, 환경 변수로 관리되는 서버는 마법사 변경을 완전히 거부합니다.

• 항상 설정을 완료하거나 MCP_AUTH_TOKEN을 설정하세요. 액세스 키 없이 구성되지 않은 서버는 열려 있습니다 — URL을 찾는 사람이 연락처 센터를 제어할 수 있습니다.

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

• manage_dnc remove 및 delete_list는 특별한 주의가 필요합니다. about 지침은 AI에게 사용 전에 확인하도록 지시합니다.

• 콘솔은 액세스 키를 브라우저의 localStorage에만 저장하며, 호출은 자체 Worker에 대한 동일 출처 요청으로 이루어집니다.

💻 개발

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

로컬 비밀을 .dev.vars(gitignored)에 넣으세요:

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 제작