genesys-mcp

당신의 Genesys Cloud 조직을 AI의 손안에. Cloudflare Workers에서 실행되는 Genesys Cloud용 오픈소스 MCP 서버입니다. 의존성이 전혀 없고 터미널이 필요 없으며, 그 목적은 온전히 구축하는 것입니다: 큐, 스킬, 사용자, 랩업 코드, Architect 플로우.

읽기만 하는 것이 아니라, 구축합니다.

Claude(또는 다른 MCP 클라이언트)에게 프롬프트하세요:

• "Weekend Support라는 큐를 생성해 줘"

• "전화 플로우를 구축해: 발신자에게 인사하고, 1번은 Weekend Support, 9번은 통화 종료. 먼저 다이어그램을 보여 줘"

• "내 Main IVR을 다이어그램으로 그려 줘"

• "온보딩 준비: 스페인어 스킬을 만들고 Jess에게 숙련도 4로 할당해 줘"

플로우 빌더는 실제 Archy YAML을 구성하고, Mermaid 다이어그램으로 플로우를 채팅에 표시한 다음, Genesys 자체 플로우 작업 파이프라인(CX as Code가 사용하는 것과 동일한 파이프라인)을 통해 게시합니다. 따라서 Genesys가 서버 측에서 검증하고 게시합니다.

의도적으로 하지 않는 것

• 분석 또는 KPI 도구는 없습니다. 이 영역은 이미 다루어지고 있습니다. MCP를 통한 대화 분석이 필요하면 MakingChatbots의 genesys-cloud-mcp-server를 확인하세요.

• 연락처 목록 관리는 없습니다.

• 삭제 기능은 없습니다. 삭제 도구가 없으며, 원시 API 도구는 DELETE를 거부합니다. 설계상 생성 우선입니다.

나만의 서버 배포하기: 3단계

1. 배포: 버튼을 클릭하거나(무료 Cloudflare 계정), git clone + npx wrangler deploy를 실행하세요. CONFIG KV 네임스페이스는 자동으로 프로비저닝됩니다.

2. Genesys OAuth 클라이언트 생성: 관리 → 통합 → OAuth → 클라이언트 추가 → 권한 유형 Client Credentials → 역할 할당(역할 범위 지정 참조) → 저장.

3. 구성: 새 Worker에서 /setup을 열고 Client ID, Secret, 리전을 붙여넣으세요. 마법사는 저장 전에 Genesys에 대해 실시간으로 검증한 후 액세스 키를 제공합니다(한 번만 표시).

터미널에서 구성을 관리하시겠습니까? 대신 Wrangler 시크릿을 설정하세요. 마법사보다 우선합니다: GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET, GENESYS_REGION(예: usw2.pure.cloud), MCP_AUTH_TOKEN.

AI 연결

MCP 엔드포인트는 https://<your-worker>/mcp입니다.

• Claude(웹/데스크톱): 설정 → 커넥터 → 사용자 지정 커넥터 추가 → URL을 붙여넣으세요. 인증 화면이 나타나면 액세스 키를 붙여넣으세요.

• Claude Code: claude mcp add --transport http genesys https://<your-worker>/mcp 실행 후 프롬프트가 표시되면 인증하세요.

• ChatGPT: 설정 → 커넥터 → 고급 → 개발자 모드 → MCP 서버 URL 추가.

• 그 외: OAuth 2.1과 함께 표준 스트리밍 HTTP MCP(또는 액세스 키를 Bearer 토큰으로 전송).

그런 다음 *"연결을 확인하고 내 큐 목록을 보여 줘"*라고 시도해 보세요.

도구 상자 (25개 도구)

✏️ = 쓰기 도구. 모든 항목은 이름을 GUID로 자동 변환하므로 "Weekend Support 큐"처럼 그냥 사용하면 됩니다.

플로우 빌더 작동 방식

1. build_flow는 스펙(인사말 + DTMF 메뉴 + 큐 전송)을 Archy YAML과 Mermaid 다이어그램으로 변환합니다. AI가 먼저 다이어그램을 보여줍니다.

2. publish_flow는 Architect 플로우 작업을 등록하고 YAML을 업로드한 후 폴링합니다. Genesys가 서버 측에서 검증하고 게시하며, 검증 오류는 그대로 반환됩니다.

3. render_flow는 조직에 이미 존재하는 플로우도 다이어그램으로 만들 수 있고, export_flow는 모든 플로우를 YAML로 다시 내보냅니다.

TTS는 플로우에 인라인으로 포함되어 있으므로(조직의 TTS 엔진이 이를 음성으로 읽음) 녹음하거나 업로드할 오디오 파일이 없습니다.

보안 모델

• 당신의 Genesys 자격 증명은 당신의 Cloudflare 계정(Wrangler 시크릿 또는 자동 프로비저닝된 KV)에만 저장되며 다른 곳에는 저장되지 않습니다.

• AI는 OAuth 클라이언트 역할이 허용하는 작업만 수행할 수 있습니다. 범위를 지정하면 Genesys가 이를 강제합니다.

• MCP 엔드포인트는 액세스 키(원시 Bearer 또는 커넥터용 내장 OAuth 2.1 흐름)를 요구합니다.

• 삭제 도구는 존재하지 않으며, genesys_api_call은 DELETE를 완전히 거부합니다.

역할 범위 지정

여기에 있는 모든 기능이 작동하려면 OAuth 클라이언트 역할에 다음 권한이 필요합니다: 라우팅(큐, 스킬, 랩업 코드) 보기 + 추가, 디렉터리 사용자 보기 + 편집(스킬 할당용), Architect 플로우 보기 + 추가 + 편집 + 게시, 텔레포니 DID 보기. Master Admin은 샌드박스에서 작동하며, 프로덕션에서는 범위를 축소하세요. 서버는 할당한 역할만큼만 강력할 수 있습니다.

로컬 개발

git clone https://github.com/ryanshatz/genesys-mcp
cd genesys-mcp
cp .dev.vars.example .dev.vars   # or create it: GENESYS_CLIENT_ID / GENESYS_CLIENT_SECRET / GENESYS_REGION / MCP_AUTH_TOKEN
npm test                          # zero-dep unit tests (node --test)
npm run smoke                     # live read-tools smoke against your org
npm run smoke -- --writes         # also exercises create tools (MCP_Test_* artifacts)
npm run dev                       # wrangler dev

정보

공개적으로 Ryan Shatzkamer(outboundIQ 기술 서비스 디렉터)이 구축했습니다. five9-mcp의 제작자이며, 동일한 제로 의존성 아키텍처를 두 번째 플랫폼에 적용했습니다. 이슈와 PR을 환영합니다. 로드맵은 이슈 트래커입니다.

MIT