Genesys MCP Server
laggyzee/genesys-mcp
Acesso leitura-apenas ao Genesys Cloud para ops e analytics em Claude
Ver no GitHubServidor MCP que conecta Claude Code diretamente ao Genesys Cloud em modo leitura, permitindo análises operacionais de contact center via linguagem natural. Oferece 58+ ferramentas para investigar desempenho de filas, avaliações de agentes, taxa de contatos repetidos, FCR, sentimento por marca e deep-dives em conversas.
Instalação
npx convez-ai laggyzee/genesys-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise de desempenho de filas e agentes em contato centers
- Investigação de contatos repetidos e cálculo de FCR (First Contact Resolution)
- Relatórios de sentimento por marca e monitoramento de tendências
- Root-cause analysis de padrões de chamadas e capacidade vs demanda
Veredito

MCP server maduro e especializado para operações de contact center no Genesys Cloud. Exige credenciais válidas e conhecimento técnico do ecossistema Genesys, mas resolve completamente o gap de acesso programático para análises via Claude — uma solução de nicho bem executada.
README
A tradução para o português deste README ainda está na fila.
genesys-mcp
A local stdio MCP server that gives Claude Code (or any MCP-compatible client) read-only access to a Genesys Cloud tenant.
Built so contact-centre operations and analytics work — queue performance, agent reviews, conversation deep-dives, repeat-caller root-cause analysis, presence/break/away analysis, demand-vs-capacity vs WFM, monthly contact-centre reports — can be done by talking to Claude in plain English instead of clicking through Genesys Admin or Performance dashboards.
v1.24.0 — September 2026: Repeat Contacts & FCR. New
get_repeat_contact_reporttool reports the Repeat Contact Rate and the derived FCR (= 1 − repeat rate) for every window × channel — 7 / 45 days (configurable) × Voice / Messaging / Combined — with cross-channel customer identity (External Contact link → merge/canonical resolution → identifier lookup → normalised raw identifier), a per-channel identity coverage block, a lookback that matches but never counts, optional by-day / by-queue breakdowns and a repeat-conversation drill-down. Scope and identity rules live in a runtime-editablerepeatContactReportconfig (get_repeat_contact_config/set_repeat_contact_config, plusGENESYS_MCP_REPEAT_*env pins). Settled day-slices and contact resolutions are cached on disk so adjacent periods don't refetch the lookback. 783 tests; 58 tools.v1.23.0 — September 2026: brand-level sentiment. New
sentiment_summarytool answers "what was each brand's sentiment last week, and did it move?" in one call — wraps the transcript-aggregates endpoint (oSentimentScore+ customer phrase counts) grouped by queue × media, rolls up to brand via tenant.yamlqueues.name_pattern(skip-listed queues excluded), fires the prior period in parallel fordelta_sentiment, and keeps no-queue bot/flow rows in a separateunattributedblock instead of dragging brand means down. Soft-fails on 403 naming the exact scope. 708 tests; 55 tools.v1.20.0 — July 2026: participant-attribute search rewritten against the endpoint's real contract. The Genesys endpoint only supports conversationId/startTime/endTime/divisionId as searchable fields, so the old attribute-criterion request drew a 400 "Search not supported." on every call once the product flag was enabled.
search_conversations_by_attributenow pulls startTime windows (4h, or 12h for spans over a week; cursor-paginated, newest first, deduplicated) and filters attributes client-side: "key exists with any value" is the default (no more 0–10 enumeration silently dropping "9.0"/"N/A"/non-0–10 scales), a newavailable_keysblock lists every key actually seen (with a "did you mean" note on case mismatches), NPS detection tolerates whole-number decimals and no-response sentinels, and queue/agent row ids come from a batched analytics details lookup (best-effort). 30-day retention clamping, a page budget, andconversations_scanned/truncatedkeep the limits honest. Rebuild-only — same tool name/count, output additive. 679 tests; 52 tools.v1.19.0 — July 2026: recent conversation-detail fallback. When the async conversations/details archive watermark is behind,
repeat_caller_reportandrepeat_caller_deep_divenow paginate the synchronous details query and accept it only when every reportedtotalHitsrow was retrieved exactly once. The tools expose whether the result is complete, provisional, archived, which endpoint supplied it, and the pagination validation. Daily-brief consumers can therefore include yesterday’s repeat-caller section while retaining the later authoritative archive repair.v1.18.0 — July 2026: fresh-presence fallback + utilization correctness. When Genesys' archived users/details watermark is behind,
presence_sessionsandbreak_overrun_reportnow use the recent synchronous details endpoint and accept it only after reconciling active-user durations against qualified user aggregates; the response says whether data is complete, provisional, archived, and which source was used.agent_utilizationno longer groups by the invalidroutingStatusdimension: it groups byuserIdand reads routing/presence categories from metric qualifiers, restoring agent effectiveness and occupancy comparisons. Conversation-detail watermark fields survive summary mode. Startup logs andmcp_health_checknow expose the installed MCP version so stale deployed images are obvious. See the full v1.18 notes for the source-selection, reconciliation, and failure contracts.v1.17.0 — July 2026: details-datalake availability. Presence and repeat-caller tools now query the relevant Genesys availability watermark and explicitly mark recent results incomplete when the requested interval extends past it. Users/details and conversations/details are tracked separately, preventing a successful async job from being mistaken for complete data when its datalake is still settling.
v1.16.0 — July 2026: customer-first callback correctness. New
callback_outcomesclassifies conversation details into reached/bridged/not-answered/never-dialled outcomes. Callback aggregate rows no longer report misleading answered or abandoned percentages: customer-first callback outcomes book onto the bridged voice leg, so callback media aggregates cannot measure reach rate.v1.15.0 — July 2026: endpoint-correctness pass. A batch of request/response-shape fixes verified against the Genesys Platform API schema:
search_conversationsnow puts ani/queue/user/direction predicates insegmentFilters(they were silently ignored inconversationFilters);routing_diagnostic's outcome/transfer/eligibility classification now uses real fields (agent-interact segments +disconnectType, not the nonexistentflaggedReason/segmentType=="transfer") and no longer fabricates skill eligibility;agent_adherence_reviewreadsresult.entities(not top-levelentities) and adds anexplanations_availableflag so a fetch failure can't be mistaken for "no explanation exists";wfm_schedule's management-unit discovery no longer calls a 404-only endpoint;search_conversations_by_attributenow paginates via the endpoint's realcursorfield instead of apageCountthat was never returned. Plus smaller field-name corrections (recording duration, time-off reviewer, workforce hire date, external-contact identifier types, a bad permission name in a utilization note) and two client-resilience fixes (401 refresh now re-authenticates the same client object; a non-numericRetry-Afterheader no longer crashes the retry loop). 616 tests; 52 tools.v1.14.1 — June 2026: bug fix.
agent_adherence_history(added in v1.14.0) used the MU-levelhistoricaladherencequeryendpoint, which is notification-only — it returnsdownloadUrls: []and delivers the result over a notification topic, so the tool always soft-failed "still processing" (verified live). Rewired to the bulk historical-adherence jobs API (POST /adherence/historical/bulk→ pollGET …/bulk/jobs/{id}→ presigneduserResultsdownload), which is genuinely synchronous-pollable and completes in seconds. Signature is nowmanagement_unit_ids: list[str](one item per MU). Works underworkforce-management:readonly— no extra scope needed. 593 tests; 52 tools.v1.14.0 — June 2026: WFM accuracy + adherence coverage. (1) New
agent_adherence_historytool returns actual-vs-scheduled adherence % / conformance % in-session (submits the async Genesys historical-adherence query, then polls the result download) — the numbersagent_adherence_reviewdeliberately doesn't compute. (2)wfm_schedulefixed: shift hours are now bucketed by the business-unit/tenant timezone (was UTC.date(), mis-attributing Sydney shifts to the wrong day — the phantom "11.5h Saturday"), published schedules only, and shift activities de-duplicated so overlapping schedules can't double-count. (3) Long (multi-year) analytics-aggregate spans now chunk into ≤12-month sub-queries and merge inqueue_performance/agent_performance/agent_utilization/volume_vs_forecast. (4)agent_utilization's missing-scope note reworded so the agent reportsanalytics:agentRouting:viewas a missing scope, not a tenant block. Tool-selection guidance added touser_activity_history(multi-year trends) andsearch_conversations_by_attribute(NPS). 592 tests; 52 tools.v1.13.2 — June 2026: bug fix.
wfm_time_off_requestswas callingPOST /businessunits/{id}/timeoffrequests/query— an endpoint that doesn't exist in the Genesys Platform API schema. Every call 404'd, surfacing as "unplanned leave not found" in reports. The real endpoint is MU-scoped at/managementunits/{muId}/timeoffrequests/query(permwfm:timeOffRequest:view). Fixed by adding requiredmanagement_unit_idsparam and fanning out one query per MU viaThreadPoolExecutor.cc-monthly-reportSKILL.md updated to pass MU ids. 568 tests; 51 tools.v1.13.1 — June 2026: bug fix.
list_org_presencesno longer crashes with "unexpected keyword argument 'page_size'" — removed pagination kwargs fromget_presence_definitions(the endpoint returns all definitions in one response; the SDK method allowlist isdeactivated/divisionId/localeCodeonly). Also fixed the silently-swallowed same-bug call in_load_presence_label_cache. Regression test pins that no pagination kwargs reach the SDK. 564 tests; 51 tools.v1.13 — June 2026: cc-workforce-history skill. New skill wraps the v1.12
user_activity_historytool with a multi-year HTML report: (1) active-agent headcount + joiners + leavers per quarter, (2) mean + median tenure trend, (3) per-person first/last active table with joiner/leaver pills. Surfaces adata_starts_atcallout so callers can interpret pre-retention quarters honestly. Renders the v1.12.1 soft-fail envelope as a clear missing-scope page instead of crashing. 563 tests; 51 tools.v1.12.1 — June 2026: wrap-up soft-fail envelope. Closes a silent-failure → LLM-narrative bug class. When
wrap_up_code_distributionhits a 403 (missinganalytics:conversationAggregate:view), the tool now returns the v1.3 canonical soft-fail envelope and the skill renders a visible "⚠️ data not retrieved" callout with the exact missing scope — no more agent-invented "Wrap-code dataset could not be retrieved" narrative paragraphs. SKILL.md instructions tightened to forbid narrative fallback. 552 tests; 51 tools.v1.12 — June 2026: workforce history. New
user_activity_historytool reconstructs each user's first/last handled-interaction date across active + inactive + deleted users (onestate=anydirectory call) and rolls up quarterly headcount, joiner/leaver flags, and mean/median tenure trend. Long windows (3+ years) are chunked into ~yearly slices and fired concurrently. Surfacesdata_starts_atso callers can tell pre-retention from no-activity. Answers "active-agent headcount per quarter Jul 2023 → now + tenure trend + first/last-active table" in one call. 549 tests; 51 tools.v1.11 — June 2026: skill wiring catch-up. No new MCP tools — surfaces every tool added since v1.6 (
agent_utilization,wfm_time_off_requests,search_conversations_by_attribute,wrap_up_code_distribution) inside the three reporting skills so daily briefs, monthly reports, and coaching packs render NPS, agent/experience scores, wrap-up code distribution + trend, leave summaries, and per-agent occupancy + disposition mix automatically. Every section is gated on the matching tenant.yaml field — tenants that opt out see no broken renders. 524 tests; 50 tools.v1.10 — June 2026: wrap-up code distribution + trend. New
wrap_up_code_distributiontool answers "which wrap-up codes did agents use this month, and which ones moved most vs last month?" — usesgroupBy: ["wrapUpCode"]on Genesys' conversations-aggregates endpoint to get per-code counts in one API call (no more N+1 per-conversation walks), resolves UUIDs to names via a cached catalogue, and fires a second parallel call for the prior interval to surface deltas / movement / new + retired codes. Closes the "Wrap-up code distribution not available in this run" gap incc-monthly-reportandcc-daily-brief. 482 tests; 50 tools.v1.9 — June 2026: relicensed MIT → PolyForm Noncommercial 1.0.0. Source-available, dual-licensed model. Noncommercial use (personal, research, evaluation, education, nonprofits/public-research/government) remains free; commercial use requires a separate licence from the maintainer.
v1.8 — June 2026: conversation attribute search + NPS auto-detection. New
search_conversations_by_attributetool answers "what's the NPS today?" and "how many conversations had outcome = Resolved?" — wraps Genesys' dedicated participant-attribute search endpoint, computes the standard NPS rollup automatically when values look 0-10 integer, and surfaces a value distribution for non-numeric attributes. New optionalsurveyblock intenant.yamllets tenants configure their NPS / Agent Score / Experience Score attribute keys for upcoming skill wiring (v1.10). 466 tests; 49 tools.v1.7 — June 2026: leave / time-off reporting. New
wfm_time_off_requeststool answers "who took leave last 4 weeks?" — pulls every approved/pending time-off request over an interval, resolves the activity code (Annual Leave / Sick / Personal / etc.) to a human-readable name via a new cachedwfm_activity_codeslookup, and rolls up totals per user and per leave type. Handles full-day and partial-day requests uniformly. 453 tests; 48 tools.v1.6 — June 2026: agent utilization. New
agent_utilizationtool answers "how much on-queue time did each agent have, how many calls + messages did they take, and what's the ratio?" — combining routing-status durations (ON_QUEUE/INTERACTING/IDLE/NOT_RESPONDING/OFF_QUEUEseconds) with answered counts in one call. Three pre-computed productivity ratios: interactions-per-on-queue-hour (headline), occupancy %, and voice-to-message ratio. Fires the two underlying Genesys aggregates endpoints concurrently. 431 tests; 46 tools.v1.5 — June 2026: interval clarity + cross-app robustness. New
compute_intervaltool turns a period keyword (today,last_week,last_28_days, etc.) into a tenant-timezone-aware ISO interval — foreign LLMs no longer need to do timezone math. The four analytical tools (queue_performance,agent_performance,repeat_caller_deep_dive,break_overrun_report) now echointerval+as_of_utcat the top of every response so persisted-file readers see the window in the first lines (closes a real cross-app hallucination bug). Five tool modules deduped onto a single_intervalsmodule — no behaviour change for existing callers. 409 tests; 45 tools.v1.4 — June 2026: call quality + batch ergonomics. New
voice_call_qualityreturns MOS scores per conversation — the "was it the network or the agent?" signal.get_user_presence_nowresolves presence UUIDs to friendly labels with a process-lifetime cache.find_usergains a batch variant for resolving 10-20 names in one concurrent call.agent_adherence_reviewfans its per-user adherence queries out via thread pool (5-10× faster on large tenants). 361 tests; 44 tools.v1.3 — June 2026: soft-fail consistency + missing discovery tool. Every tool now uses a canonical soft-fail envelope (
status/kind/message/ id fields). Newlist_org_presencesexposes the discovery path for the pre-break presence UUID.get_conversation,queue_estimated_wait_time, andlookup_external_contactall migrated to the shared envelope.v1.2 — June 2026: inline transcripts. New
get_conversation_transcriptreturns structured, time-aligned utterances with speaker labels and optional per-utterance sentiment. The coaching pack uses it automatically — every flagged call ships with an inline transcript excerpt so TLs can read what was said without per-call round-trips.v1.1 — May 2026: the token-budget release. Four heavy analytics tools (
queue_performance,agent_performance,repeat_caller_deep_dive,break_overrun_report) gain amode: "summary" | "full"parameter, defaulting to summary. Routine interactive queries use roughly 25–40% of the v1.0 token count with zero loss of signal for any current skill.v1.0 — May 2026: the tenant-agnostic + correctness floor release. Every tenant-specific assumption that used to be baked into Python now lives in
tenant.yaml. A newoperating_modelblock lets single-brand, message-only, and no-pre-break tenants get clean degraded reports instead of misleading zeros. Queue-name pattern is optional and the loader hard-fails on schema-version drift.See RELEASE-NOTES.md for the full history.
What it does
Curated tools for ops/analytics work — queues, agents, conversations, recordings, speech analytics, external contacts, workforce management — plus a generic call_genesys_api escape hatch for anything not yet wrapped.
Read-only by design. The server expects a Client Credentials OAuth client whose role only has *:readonly scopes. Even if Claude tried to POST/PUT/DELETE through the escape hatch, Genesys refuses server-side. There are no write tools.
Will this work on my tenant?
v1.0 was the explicit shift from "works on one specific Genesys setup" to "works on any Genesys Cloud tenant — and tells you up-front where your shape differs." Three categories of assumption you can toggle via tenant.yaml:
| Assumption | Default | Toggle off if |
|---|---|---|
| Pre-break presence as drain state — agents go BUSY/"Pre Break" before scheduled breaks to drain interactions | enabled | your CC doesn't use a pre-break presence; reports render a "tracking disabled" callout instead of zero rows |
| Multi-brand structure — multiple brand display names share the same CC | enabled | single-brand tenant; reports collapse brand × channel rollup to channel-only |
| Voice + message channels | both | message-only / voice-only tenant; headline KPI cards skip the irrelevant channel |
Queue naming pattern — {brand} - {channel} - {function} | matches > 80% | your queues use a different convention; set name_pattern_match_required: false to fall back per-queue, or name_pattern: null for no structured parsing |
| Specialist role title | ["Specialist", "Customer Service Specialist"] (no in-code default in v1.0 — discovered by the setup wizard) | your active users' titles differ; the wizard discovers what's actually in use |
Run python -m genesys_mcp.health_check --strict after setup. It samples a page of queues to compute the pattern-match rate, cross-checks specialist_roles against active user titles, and validates every other tenant.yaml field against the live data. Exit code 0 (ready), 2 (warnings — --strict), or 1 (blocked). Use the warnings to decide which operating_model toggles to flip.
Setup
Requires Python 3.11+ (developed against 3.14).
Quickstart (v0.6+) — one-command install
After creating your OAuth client (step 1 below), the fastest path is:
git clone https://github.com/laggyzee/genesys-mcp.git
cd genesys-mcp
./install.sh
The installer syncs deps, prompts for OAuth creds, registers the MCP with Claude Code, symlinks every skill into ~/.claude/skills/, and runs the health check. Idempotent — re-running it upgrades cleanly.
If you'd rather do it manually, follow the numbered steps below.
1. Create a Genesys OAuth client
Genesys Admin → Integrations → OAuth → Add Client.
- Grant type: Client Credentials
- Roles: create or attach a role with these readonly permissions:
- Required for the core tools:
analytics,conversations,recordings,users,routing - Optional (Wave 3 tools):
speech-and-text-analytics,external-contacts,workforce-management - Optional (v0.5 coaching tools):
quality— enables theqa_evaluationstool and the QA section ofagent_coaching_pack/ thecc-coaching-prepskill. Without it, the QA section soft-fails (returnsscope_available: false) and the rest still works.
- Required for the core tools:
Copy the Client ID and Client Secret somewhere safe.
2. Configure environment variables
git clone https://github.com/laggyzee/genesys-mcp.git
cd genesys-mcp
cp .env.example ~/.config/genesys-mcp.env
chmod 600 ~/.config/genesys-mcp.env
# Edit ~/.config/genesys-mcp.env and paste your client_id / client_secret.
# Set GENESYS_REGION to your tenant's region (see list below).
Supported regions: ap-southeast-2 (Sydney), us-east-1 (Virginia), eu-west-1 (Ireland). Add more in client.py if you need them — the SDK supports all Genesys public regions.
3. Install
uv sync # or: pip install -e .
4. Wire into Claude Code
Edit ~/.claude/mcp.json (or your platform's equivalent) and add:
{
"mcpServers": {
"genesys": {
"command": "uv",
"args": ["run", "--directory", "/path/to/genesys-mcp", "python", "-m", "genesys_mcp.server"],
"env": {
"GENESYS_CLIENT_ID": "...",
"GENESYS_CLIENT_SECRET": "...",
"GENESYS_REGION": "ap-southeast-2"
}
}
}
}
Restart Claude Code and the genesys MCP server will start automatically.
5. (Optional) Set up the tenant config — needed for cc-monthly-report and other tenant-aware skills
Skills that produce tenant-aware artefacts (currently just cc-monthly-report, more in future) read tenant-specific knobs — brand list, queue naming pattern, WFM management unit, AHT targets, pre-break presence, output filename — from a single YAML file at ~/.config/genesys-mcp/tenant.yaml (or $GENESYS_MCP_CONFIG). The MCP server itself doesn't need this; only the dependent skills do.
Easiest way to populate it: ask Claude "set up genesys mcp for my tenant" — that triggers the genesys-tenant-setup skill, which:
- Auto-discovers everything it can from your read-only OAuth client (queue naming pattern, brand list, WFM units, pre-break presence, specialist roles)
- Asks you a short list of policy questions for the rest (tenant display name, AHT targets, output filename)
- Validates the result against the schema and writes it to
~/.config/genesys-mcp/tenant.yaml
Or by hand: copy skills/cc-monthly-report/tenant.example.yaml to ~/.config/genesys-mcp/tenant.yaml and fill in the values. Schema reference: docs/tenant-config-schema.md.
Tool surface
Directory & lookups
| Tool | Purpose |
|---|---|
list_queues | List routing queues, optionally filtered by name |
list_users | List active/inactive users |
find_user | Free-text search by name or email (uses /api/v2/users/search). v1.4: optional name_contains_list runs N searches concurrently for TL workflows that need a target + peer set in one call. |
find_user_by_email | Exact email lookup |
get_queue_members | Who's a member of a given queue, with routing status |
list_wrapup_codes | Resolve disposition UUIDs to names |
list_routing_skills / get_user_skills | Skill catalogue and per-user mapping |
list_org_presences | (v1.3) Org-level presence definitions with UUIDs + labels. Filter by name_contains. Closes the "what's my pre-break presence UUID?" discovery gap — pair with break_overrun_report config. |
compute_interval | (v1.5) Convert a period keyword (today, yesterday, this_week, last_week, this_month, last_month, last_7_days, last_28_days) to a tenant-timezone-aware ISO interval. Returns a paste-ready interval string for the analytical tools. Call this before any analytical tool when you want a calendar-aligned window in the tenant's local time. |
get_user_routing_status / get_user_presence_now | Real-time per-user status. v1.4: get_user_presence_now resolves the presence definition UUID to a friendly label ("Pre Break", "Coaching", etc.) via a process-lifetime cache. |
get_user_queues | Which queues an agent is joined to |
Real-time & analytics
| Tool | Purpose |
|---|---|
queue_observation | Live snapshot — waiting / interacting / on-queue agents |
queue_estimated_wait_time | Genesys' own AI-adjusted EWT model |
queue_performance | Per-queue × media aggregates. Raw metrics match the Genesys "Performance > Queues" UI exactly (tAnswered.count = UI "Answer" column, etc.). Derived fields computed by the MCP — verify via mcp-reconcile before any release: answered, abandoned, service_level_pct, avg_wait_s, avg_answer_s, avg_handle_s. Filter shape mirrors the UI's canonical and+or+or form. |
agent_performance | Per-agent productivity, split per media (voice / message / email / callback). Raw metrics match "Performance > Agents" UI exactly (tAnswered.count, tHandle.sum/count). Headline fields: answered, handled, avg_handle_s, avg_talk_s, avg_acw_s, transfer_rate_pct, plus a by_media breakdown. (Was materially wrong in v0.1 — see release notes.) Aggregation across buckets / per-media split is MCP logic; cross-check with mcp-reconcile. |
agent_utilization | (v1.6) Per-agent routing-status durations (ON_QUEUE / INTERACTING / IDLE / NOT_RESPONDING / OFF_QUEUE seconds) plus answered counts (voice / message / callback) in one call. Three pre-computed ratios: interactions_per_on_queue_hour (headline), occupancy_pct, voice_to_message_ratio. Sorted by interactions-per-hour desc — high-throughput agents at the top, agents with no on-queue time at the bottom. Soft-fails on 403 against the routing-status scope (answered counts still populate). |
presence_sessions | Per-user break/meal/away sessions over an interval — wraps the analytics/users/details async-jobs flow into a single call |
Conversations & recordings
| Tool | Purpose |
|---|---|
search_conversations | Search by ANI, queue, agent, direction, time window |
get_conversation | Full conversation detail |
list_recordings | Recording metadata |
get_recording_url | Signed URL for downloading a single recording |
voice_call_quality | (v1.4) Per-conversation MOS (Mean Opinion Score) for voice-call quality triage. quality_label: good/fair/poor lets coaching briefs flag the "was it the network or the agent?" angle before suggesting agent coaching. Up to 100 conversation ids per call; configurable low_mos_threshold (default 3.5). |
Composition reports
| Tool | Purpose |
|---|---|
repeat_caller_report | Pulls voice/message/callback details for an interval, groups by ANI, splits the funnel into IVR-only / ACD-offered / answered / abandoned-in-queue per repeater, plus an org-wide funnel block |
repeat_caller_deep_dive | The why layer on top of repeat_caller_report. Enriches the top repeaters with conversation summaries, AI outcomes (Resolved / Mid Flight / Unresolved Chat / Escalated), expected-fix tags, sentiment trajectory, and a heuristic recommended_action (callback_recommended / escalate_to_retention / route_review / monitor). Org rollup includes top dispositions and the unresolved_repeaters priority list. |
get_repeat_contact_report | (v1.24) Repeat Contacts & FCR. period_start / period_end (local dates, inclusive) → one row per window × channel: total_contacts, repeat_contacts, repeat_rate, fcr (FCR = 1 − repeat rate, derived not measured), unidentified_contacts, raw_key_contacts, identity coverage, config_used, warnings[]. A contact is one conversation; it is a repeat if the same customer had any prior in-scope contact within N local calendar days. Voice / Messaging match same-channel priors only, Combined matches either. Lookback (period_start − max window) is fetched for matching only. Optional breakdown: ["day","queue"] and drilldown. Unspecified params fall back to the repeatContactReport config. Includes a methodology string. See Repeat Contacts & FCR. |
get_repeat_contact_config | (v1.24) Effective repeatContactReport config + which keys are pinned by GENESYS_MCP_REPEAT_* env vars. |
set_repeat_contact_config | (v1.24) Deep-merge a partial update into the stored defaults — no redeploy. Validates the whole config first (windows must be positive integers, unknown keys rejected); writes a local JSON file only, never Genesys. |
break_overrun_report | Per-agent break / meal / AWAY / PRE_BREAK signals over an interval. AWAY tracked as raw count + total minutes (no target). PRE_BREAK overruns vs configurable target (default 10 min) — handles the auto-applied pre-break presence and quantifies time spent over the drain window. |
agent_quality_snapshot | One-shot agent review combining handle stats, hold-ratio flags, silent-transcript detection, wrap-up note discipline, and optional peer comparison |
agent_coaching_pack | One-shot 1:1 prep brief: volume / AHT vs targets, peer-median comparison, sentiment + QA, wrap-up discipline, top flagged calls, and heuristic top-3 recommended coaching focus. v1.2: each flagged call ships with an inline transcript_excerpt (~40 utterances) so the brief reads end-to-end without per-call round-trips. Tenant-aware (loads AHT targets, flagged-call thresholds, and coaching heuristics from tenant.yaml). Drives the cc-coaching-prep skill. |
live_wallboard | Per-queue real-time view combining observation + EWT + agents-on-queue in one call |
Repeat Contacts & FCR (v1.24)
get_repeat_contact_report answers "what share of contacts were repeats, and what FCR does that imply?" for every combination of window (default 7 and 45 days) and channel (Voice, Messaging, Combined).
Definitions. A contact is one Genesys conversation, counted once however many sessions, segments or agents it had. A contact is a repeat if the same customer had any prior in-scope contact within the preceding N days — any reason, no intent or wrap-up matching — and the repeat is attributed to the later contact. repeat_rate = repeat_contacts / total_contacts for that channel and period; FCR (Amaysim methodology) = 1 − repeat_rate. It is derived, not measured: no survey or disposition is involved. Voice-only and Messaging-only rates need the prior contact on the same channel; Combined accepts a prior on either (a call followed by a message within N days is a repeat).
Calculation rules. Contacts from period_start − max(window) to period_start are fetched for matching only and never counted. Chains count each link. Two contacts on one day make the second a repeat. A contact never matches itself (conversations are de-duplicated by id). Day boundaries use the configured timezone, and "within N days" compares local calendar dates (a gap of exactly N days is a repeat, N + 1 is not). Scope (direction, abandoned, queues) applies to prior contacts too.
Customer identity. Every contact resolves to one customer_key, in order: (1) the participant's externalContactId, resolved to the canonical surviving contact when merged; (2) an External Contact lookup on the normalised raw identifier — first against identifiers already seen on a linked conversation in the same run (free), then the identifier-lookup API, then a contact search accepted only on exactly one match; (3) the normalised raw identifier itself (E.164 phone with a default country, email, web-messaging user id, social handle) — reported as raw_key_contacts, because raw keys rarely link a call to a message; (4) no identifier → unidentified_contacts: in the denominator, never a repeat. Every result carries coverage (count + % per method, per channel), and Combined rows carry a combined_rate_likely_understated warning when the External Contact share is below identity.low_coverage_warning_pct.
Config — section repeatContactReport. Layered: built-in defaults → a repeatContactReport: mapping in tenant.yaml → the runtime store written by set_repeat_contact_config ($GENESYS_MCP_REPEAT_CONTACT_CONFIG, else repeat-contact-report.json beside tenant.yaml) → GENESYS_MCP_REPEAT_* env pins (which win, and are reported as env_overridden_keys).
| Key | Default | Env override |
|---|---|---|
direction | inbound (outbound, all) | GENESYS_MCP_REPEAT_DIRECTION |
include_abandoned | false — queued but never handled by an agent | …_INCLUDE_ABANDONED |
include_pre_queue | false — ended in IVR / bot before any queue or agent | …_INCLUDE_PRE_QUEUE |
media_types.voice / .messaging | ["voice"] / ["message"] (all message subtypes) | …_VOICE_MEDIA_TYPES, …_MESSAGING_MEDIA_TYPES |
queue_ids | [] = all queues | …_QUEUE_IDS |
windows_days | [7, 45] — positive integers, custom windows allowed | …_WINDOWS_DAYS |
timezone | Australia/Sydney | …_TIMEZONE |
identity.mode | external_contact_first (or raw_only) | …_IDENTITY_MODE |
identity.enable_lookup | true — identity step 2; adds API volume | …_IDENTITY_ENABLE_LOOKUP |
identity.resolve_canonical | true — merge resolution via bulk contact fetch | …_IDENTITY_RESOLVE_CANONICAL |
identity.max_lookups_per_run | 5000 — period contacts are looked up first | …_IDENTITY_MAX_LOOKUPS |
identity.phone_normalisation | {format: "E.164", default_country: "AU"} | …_PHONE_DEFAULT_COUNTRY |
identity.messaging_keys | [email, sms, web_messaging_user, social] | …_MESSAGING_KEYS |
identity.low_coverage_warning_pct | 70 | — |
drilldown_max_rows | 2000 per window × channel | — |
cache.* | enabled: true, settled_after_hours: 24, retention_days: 120, identity_ttl_hours: 24 | …_CACHE_ENABLED, …_CACHE_DIR |
Performance and caching. Conversations are fetched one local day at a time (async details jobs once the archive watermark covers the day, validated synchronous paging before that), fully paged, and reduced to slim records straight away. A cold 45-day lookback walks ~50 day-slices and resolves every distinct External Contact in batches of 50, so the first run can take several minutes on a busy tenant — give the MCP client a generous timeout. Settled, complete days and contact resolutions are cached under $GENESYS_MCP_CACHE_DIR (default ~/.cache/genesys-mcp/repeat-contacts/<tenant hash>/), so adjacent periods and re-runs only fetch new days. The cache contains customer identifiers: files are written 0600 in a 0700 directory, namespaced per OAuth client, and pruned after cache.retention_days. Set cache.enabled: false to opt out.
Scopes. analytics:conversationDetail:view; External Contact resolution also needs externalContacts:contact:view (external-contacts:readonly) and degrades to link + raw-key identity with an external_contacts_unavailable warning without it.
Quality management (needs quality:readonly)
| Tool | Purpose |
|---|---|
qa_evaluations | Per-agent Quality Management evaluation summary over an interval: avg score, pass rate, critical-pass rate, last-evaluated, per-evaluation rows (form, evaluator, score, conversation id). Optional per-question detail + evaluator comments via include_question_detail=True. Soft-fails with scope_available: false when the scope isn't granted. |
Routing diagnostics
| Tool | Purpose |
|---|---|
routing_diagnostic | Explains why a specific conversation routed (or didn't) as expected: IVR → queue → outcome path with durations, queue routing rules, eligible-agent counts (session-level from Genesys, current-state for the queue), abandon / answer / transfer classification. |
routing_diagnostic_aggregate | (v0.9) Aggregate failure-mode analysis for a queue over an interval. "Show me all this week's abandons on our general inbound queue — how many were because nobody was eligible vs. all-busy? Which 15-minute windows were worst?" Closes the v0.5 promise. Heuristic classification: no_eligible_agents / all_eligible_busy / abandoned_in_ivr. Pairs with the v0.7 cc-daily-brief 'worst routes' section — daily-brief surfaces which queues failed; this surfaces why. |
Health check (v0.6+)
| Tool | Purpose |
|---|---|
mcp_health_check | End-to-end onboarding check: probes one representative endpoint per OAuth scope (green/red per scope), validates tenant.yaml against the schema, verifies the companion skills are symlinked into the Claude Code skills dir. Returns a verdict of ready / ready_with_warnings / blocked plus concrete remediation strings for each gap. Also available as a CLI: python -m genesys_mcp.health_check. |
Speech & text analytics (needs speech-and-text-analytics:readonly)
| Tool | Purpose |
|---|---|
get_conversation_summary | AI-generated summary (topics, key issues) |
get_conversation_sentiment | Per-speaker sentiment timeline |
sentiment_summary | (v1.23) Aggregate sentiment per queue × media and per brand over an interval, with prior-period delta. One transcript-aggregates call, not an N+1 walk. Brand rollup from tenant.yaml queues.name_pattern; no-queue bot/flow rows surfaced separately as unattributed. Needs analytics:speechAndTextAnalyticsAggregates:view (bundled into analytics:readonly on tenants verified so far). |
get_transcript_url | Signed URL to the full transcript JSON (raw — use get_conversation_transcript for parsed) |
get_conversation_transcript | (v1.2) Structured, time-aligned utterances with speaker labels (customer/agent/IVR/ACD) and optional per-utterance sentiment. `mode: "summary" |
External contacts (CRM) (needs external-contacts:readonly)
| Tool | Purpose |
|---|---|
lookup_external_contact | Phone/email → CRM record with custom fields |
Workforce management (needs workforce-management:readonly)
| Tool | Purpose |
|---|---|
list_management_units / get_user_management_unit | WFM topology |
query_agent_adherence_explanations | Why an agent was off-schedule |
agent_adherence_review | Combines presence overruns with WFM explanations side-by-side |
wfm_schedule | Per-day scheduled hours (sum of paid-time activities across user shifts) vs WFM-forecast required hours (from headcountforecast requiredPerInterval). The headline answer to "do we need more staff or just better scheduling shape?" — compares scheduled capacity against demand on every day of the period and flags understaffed days. |
volume_vs_forecast | (v0.7) Per-interval forecast vs actual comparison — closes the WFM loop alongside wfm_schedule. Pulls the published short-term forecast for an interval (/businessunits/{buId}/weeks/{weekDate}/shorttermforecasts), pulls actual conversation volume + handle time via analytics aggregates, computes per-bucket variance, and rolls up forecast accuracy (MAPE). Answers "how good was last week's forecast?" — WFM analysts currently build this in Excel. |
Escape hatch
| Tool | Purpose |
|---|---|
call_genesys_api | Generic /api/v2/* call (GET/POST/PUT/PATCH/DELETE). Non-GET will 403 unless your OAuth client has write scopes (it shouldn't). |
Example sessions
Once installed, just talk to Claude:
- "Pull last week's answer rate and SLA for our voice queues."
- "Find Jane Smith and show me her status right now."
- "What's the estimated wait time on the Sales queue?"
- "Run the repeat-caller deep dive for last week — top 25 ANIs."
- "Who's spending the most time over the 10-minute pre-break this month?"
- "How does our scheduled capacity compare to the WFM forecast for April?"
- "Pull a quality snapshot for agent X over the last 7 days, compared with their peers."
- "What's the live wallboard look like for these 6 queues?"
Companion skills
Five user-installable Claude Code skills ship with this repo. All depend on a per-tenant config at ~/.config/genesys-mcp/tenant.yaml — see Setup step 5 above for how to populate it (the easiest path is the genesys-tenant-setup wizard).
cc-monthly-report
Produces a self-contained HTML contact-centre report from one prompt — "do the monthly CC report for May 2026" — and drops it at <output_dir>/<short_name>-CC-<period>.html (paths configurable per tenant).
What the report contains:
- LLM narrative synthesis (v0.7) — four sections written by Claude on top of the data: Coverage & caveats, What worked, What went wrong, Recommended actions. Opt-in via
--with-narrative <md-file>; omit the flag for a data-only build. - Executive summary (KPI cards + headline findings)
- Volume & funnel (brand × channel totals, per-queue tables, daily voice service-level chart, plus the v0.9 hour-of-day × day-of-week heatmap that surfaces intra-day staffing patterns the daily chart averages away)
- Themes (top dispositions, AI outcome distribution, top expected-fix tags)
- Repeat callers — actionable priority list of unresolved repeaters with summaries
- Workforce — per-agent productivity (specialists only), AHT vs targets (voice / message / ACW), break / AWAY / pre-break behaviour. v0.9 adds inline-SVG voice-AHT sparklines next to each headline AHT so direction of travel is visible at a glance.
- Performance leverage — quantifies "phantom capacity" (handle hours that would be freed if every agent hit AHT target) + "FCR drag" (handle hours wasted on repeat calls), then compares against the WFM-derived peak-demand shortfall to give a single synthesised verdict: "more staff or better staff?"
Tenant-agnostic by design: every brand name, queue naming pattern, AHT target, WFM unit ID and presence ID is read from the tenant config. No tenant-specific values are hard-coded in the skill or build script.
Living at skills/cc-monthly-report/ (symlinked under ~/.claude/skills/). The skill markdown describes the workflow; a Python script does the aggregation and HTML rendering. Reproducible — the same skill against the same period and tenant config gives the same report.
cc-coaching-prep
One-prompt 1:1 prep brief for a single agent — "prep coaching for [agent name] for the last 4 weeks" — drops a self-contained HTML at <output_dir>/coaching-<agent-slug>-<period>.html.
What the brief contains:
- Performance vs targets (KPI cards + colour-coded vs-target pills for voice / message AHT and ACW)
- Peer comparison table (same-role peers, peer-median for each KPI with delta-vs-peers badges)
- Sentiment & quality (avg sentiment, QA score / pass rate / critical-pass / last-evaluated, recent evaluations table)
- Wrap-up & handling (note rate, top dispositions)
- Top flagged calls (heuristic: sentiment drop, hold ratio, AHT excess, no wrap-up notes — colour-coded reason pills with transcript links)
- Recommended coaching focus (heuristic top-3 with concrete evidence)
v0.9 adds optional LLM narrative synthesis in three sections — Strengths to acknowledge, Areas to coach, Suggested talking points — embedded in the HTML so the TL can re-read them right before walking into the 1:1 instead of scrolling chat history.
Tenant-aware: AHT targets, peer-grouping strategy (role / queue / mu), and flagged-call thresholds (sentiment drop, silent seconds, AHT-excess %) all read from coaching.* in tenant.yaml. Soft-degrades cleanly: no quality scope → QA section empty; no STA scope → sentiment section empty; the rest still populates.
Living at skills/cc-coaching-prep/.
cc-daily-brief
(v0.7) One-prompt daily brief for supervisors at start-of-day — "daily brief", "morning brief", "how did we go yesterday". Drops a one-page HTML at <output_dir>/daily-brief-<YYYY-MM-DD>.html.
What the brief contains:
- Headline KPIs — voice + message SL today vs the rolling 7-day median
- Worst routes — top queues by SL drop vs their rolling median
- Flagged agents — top agents by voice AHT excess
- Repeat-caller callback list — unresolved repeaters from yesterday
- Adherence flags — agents over the combined break/pre-break/meal overrun threshold
v0.9 adds optional LLM narrative synthesis in two sections — Headline (≤80-word paragraph framing the day vs the rolling median) + Today's priorities (top 3 actions for the supervisor's morning standup). Daily briefs are meant to be glanced at; the 4-section monthly shape would be overkill.
Tenant-aware: flag thresholds (sentiment dip, AHT excess %, SL drop pp) and the comparison window all read from daily_brief.* in tenant.yaml. Designed to fit a laptop screen or Slack share without scrolling — narrower than the monthly report.
Living at skills/cc-daily-brief/.
mcp-reconcile
(v0.8) Release-time reconciliation. "reconcile the MCP against the Genesys UI" pulls the MCP tool stack for a chosen period (default: last completed week) and outputs a Markdown checklist of side-by-side comparisons:
| ✓ | Queue | Media | MCP answered | Verify in Genesys UI |
|---|---|---|---:|---|
| ☐ | Brand A - Activation | voice | 1,247 | Performance → Queues → 18-25 May → Voice column |
You click through the live Genesys UI, tick each row off, and either confirm parity or flag a mismatch. Pairs with make test: the test suite proves the aggregator maths is stable; reconciliation proves the source numbers still match the UI. Run before each release.
Living at skills/mcp-reconcile/.
genesys-tenant-setup
Generates the per-tenant config (~/.config/genesys-mcp/tenant.yaml) by auto-discovering whatever it can from the read-only OAuth client (queue patterns, brand list, WFM units, pre-break presence, specialist roles, AHT baselines, timezone) and asking Claude conversational questions for the rest. Writes a validated YAML file when done. Run it once per tenant — anyone forking the repo will use this.
Living at skills/genesys-tenant-setup/.
Testing (v0.8+)
The aggregation layer + canonical Genesys-UI filter shapes are covered by a pytest suite:
make test
What's tested:
- Aggregators in
skills/cc-monthly-report/build_report.py— pure dict→dict functions. Golden fixtures captured from a live tenant (viatests/_capture_fixtures.py); structural assertions ensure refactors don't silently change output counts/totals. - Canonical filter shapes (
tests/test_analytics_filters.py) — the v0.2 UI-parity fix is pinned via monkey-patched-SDK tests. A regression to the pre-v0.2 flat-OR shape would fail these tests immediately. - Helper functions (formatters, threshold classifiers, sentiment/trend labellers) — parameterised unit tests; no fixtures required.
- HTML rendering — BeautifulSoup-based structural assertions on column counts, vs-target pill colours, narrative-synthesis sections.
- Conversation deep-link helper — resolution priority + region mapping + fallback rendering.
What's deliberately not tested at this layer:
- Raw MCP tool wrappers in
tools/*.py— they mostly call the SDK 1:1. Testing them mostly tests the SDK. The filter-shape assertions cover our own logic; the SDK's correctness isn't our problem. - End-to-end live-tenant calls — covered by the
mcp-reconcileskill instead: run a reconciliation checklist before each release and click each row off against the live Genesys UI.
If a refactor breaks something, the test suite catches structural drift; if Genesys changes endpoint semantics, the reconciliation checklist catches numerical drift. Both are needed.
Design
- OAuth at startup — client credentials token fetched on lifespan init, auto-refreshed on 401 via the retry helper.
- No write access from the MCP — even if the LLM tries to POST/PUT/DELETE, the OAuth scope refuses server-side. Out-of-band administrative writes (e.g. bulk agent provisioning, see Danger Zone below) use a separate, locally-invoked script with its own write-scoped OAuth client; the MCP server never loads those credentials.
- id → name resolution cache — internal
naming.Resolverlazy-loads queue/user/wrap-up names so most responses are human-readable without follow-up calls. - Composition over wrappers —
agent_quality_snapshot,repeat_caller_reportetc. chain multiple endpoints into single ops-ready reports rather than forcing the caller to do the joining.
⚠️ Danger Zone — out-of-band write scripts
The MCP server is read-only by design. For the rare administrative tasks that genuinely require writes against your tenant, the scripts/ directory contains standalone CLIs that:
- Are not registered as MCP tools — Claude cannot reach them, regardless of prompt
- Use a separate, write-scoped OAuth client (
GENESYS_WRITE_CLIENT_ID/SECRET) — the read-only MCP client is unaware of it and the server's startup code warns loudly if write credentials leak into the MCP process - Default to
--dry-run— explicit--confirmis required to write - Ship a
--self-testmode that exercises every write step against a throwaway user before you point the script at real data - Track per-user state in a ledger at
/tmp/provision_users/<run-id>/so a partial failure can resume from the failing step
Read scripts/README.md before running anything in this directory. It documents the one-off Genesys admin setup (a separate OAuth client + a tightly-scoped custom role), the tenant assumptions the scripts make (e.g. roles inherited from group membership), and the precise list of permissions to grant.
Currently shipped
| Script | What it does |
|---|---|
provision_users.py | Bulk-create agents from a template agent (clones division, manager, location, ACD auto-answer, addresses, title/department, profile skills, routing skills + proficiency, routing languages, group memberships, WFM management unit; sends activation invite). |
Quick reference (see scripts/README.md for the full setup and tenant-assumption notes):
# 1. Verify the OAuth role has every required scope (creates a throwaway user; you delete it manually)
python scripts/provision_users.py --self-test --template-email <existing-agent>@example.com
# 2. Dry-run a real batch (default — writes nothing)
python scripts/provision_users.py --template-email <template>@example.com --emails new_starters.txt
# 3. Actually execute
python scripts/provision_users.py --template-email <template>@example.com --emails new_starters.txt --confirm
Companion skill
Pair with the platform-api skill from MakingChatbots for endpoint discovery — useful when working with call_genesys_api.
Contributing
PRs welcome — please read CONTRIBUTING.md first. In short: sign off your commits under the DCO (git commit -s), and note that contributing also grants the maintainer the right to license your contribution under the project's commercial licence (so the project can stay dual-licensed). You keep copyright in your work.
Things on the roadmap that someone might want to take a swing at:
- Web messaging transcript wrapper (the
/api/v2/conversations/messages/{id}/messages/bulkflow, which currently needs thecall_genesys_apiescape hatch) - Half-hourly intra-day staffing in
wfm_schedule(currently rolls up to daily; the v0.9 hour-of-day heatmap covers the demand side, but scheduled-capacity bucketing is still daily) - Skill-based routing analysis (which agents have which skills × queue requirements)
- GitHub Pages site with anonymised sample reports — distribution/discoverability is the v0.10 candidate, not another feature release
Explicitly removed from the backlog: outbound campaign coverage (deferred across v0.5–v0.8, dropped in v0.9 — re-add if an outbound-shop user opens an issue). Forecast-vs-actual analysis shipped in v0.7 as volume_vs_forecast.
Licence
Source-available, not open source. This project is licensed under the PolyForm Noncommercial License 1.0.0 — see LICENSE.
- Noncommercial use is free. Personal projects, research, evaluation, education, and use by nonprofits, public-research, and government bodies are all permitted at no cost.
- Commercial use requires a separate licence. You may not use this software — or build a product or service on it — for commercial advantage or monetary compensation without a commercial licence from the maintainer. This includes selling it, offering it as a hosted/managed service, or bundling it into a commercial offering.
Commercial licensing: email designsbylwd@gmail.com, or open a GitHub issue labelled commercial-license to start a conversation.
History: all releases published before this licence change were under the MIT Licence and remain available under MIT for those versions — MIT rights already granted cannot be revoked. This and all future versions are licensed under PolyForm Noncommercial 1.0.0.