Genesys Cloud - Main

Hey all! 

Haven't posted in a while but...

I've open-sourced an MCP server I built for my own contact-centre ops work and it's been valuable enough that I figured the wider Genesys community might want it. Sharing here for feedback and to invite contributors.

Repo: https://github.com/laggyzee/genesys-mcp Licence: MIT

What is it

genesys-mcp is a local stdio Model Context Protocol server that exposes a curated, read-only set of Genesys Cloud tools to MCP-compatible AI clients (Claude Code, Cursor, Continue, etc.). Once installed, you can ask the LLM things like:

• "Pull last week's abandon rate by queue"
• "What's the live wallboard look like for these queues?"
• "Find all customers who called us 3+ times this week"
• "Did anyone go over their break or lunch this week?"
• "Pull a quality snapshot for agent X compared to peers"
• "What's the EWT on the Sales queue right now?"

…and the LLM picks the right Genesys API endpoints, makes the calls, and writes up the answer. Everything is read-only - the OAuth client uses Client Credentials with *:readonly scopes, so there's no write surface even via the escape hatch.

It's been replacing a lot of the "log into Admin → run a report → paste numbers into a spreadsheet" loop that ops teams do every day.

How it works

• Python (FastMCP) server running locally over stdio
• Official PureCloudPlatformClientV2 SDK for typed API access
• Generic call_genesys_api escape hatch for endpoints not yet wrapped, with auto 401 retry
• Internal id → name cache (queues, users, wrap-up codes) so most responses come back human-readable
• Multi-region - Sydney, Virginia, Ireland out of the box; trivial to add others

Tool surface

About 35 tools across these areas:

• Directory - list/search queues, users, skills, wrap-up codes; per-user routing status & live presence
• Real-time analytics - queue_observation, queue_estimated_wait_time (the AI-adjusted-AHT model), queue_performance with derived answered/abandoned/service_level_pct fields that match the Performance UI columns
• Conversations - search, full detail, recording metadata, signed media-download URLs
• Presence sessions - break/meal/away analysis wrapping the analytics/users/details async-jobs flow into a single call
• Composition reports - repeat_caller_report, break_overrun_report, agent_quality_snapshot, live_wallboard (each chains 2–4 endpoints into ops-ready output)
• Speech & text analytics (needs speech-and-text-analytics:readonly) - conversation summaries, sentiment, transcript URLs
• External contacts (needs external-contacts:readonly) - phone/email → CRM record lookup
• Workforce management (needs workforce-management:readonly) - management-unit topology, agent adherence explanations, combined adherence-vs-presence review
• call_genesys_api - generic escape hatch for any /api/v2/* endpoint

Full table in the README.

Setup (5-min install)

# 1. Clone
git clone https://github.com/laggyzee/genesys-mcp
cd genesys-mcp

# 2. Create an OAuth Client Credentials client in Genesys Admin
#    Required scopes: analytics:readonly, conversations:readonly,
#    recordings:readonly, users:readonly, routing:readonly
#    Optional: speech-and-text-analytics:readonly, external-contacts:readonly,
#    workforce-management:readonly

# 3. Set env vars
cp .env.example ~/.config/genesys-mcp.env
chmod 600 ~/.config/genesys-mcp.env
# edit and paste your client_id, client_secret, region

# 4. Install deps
uv sync   # or: pip install -e .

# 5. Wire into your MCP client

For Claude Code, add to ~/.claude/mcp.json:

{
  "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 you're done.

Example sessions

A few real prompts I've used this week:

Things on the roadmap (PRs welcome)

• Web messaging transcript wrapper (the /api/v2/conversations/messages/{id}/messages/bulk flow currently needs the escape hatch)
• Full async historical adherence (scheduled vs. actual percentages with shift overlay)
• Quality evaluations / scorecards (quality:readonly)
• Outbound campaign progress (outbound:readonly)

Why share?

Building this saved me probably 5–10 hours a week on routine ops reporting and made it possible to answer things like "show me agents whose wrap-up note discipline dropped this week" in one prompt instead of an afternoon of clicking. If anyone in this community gets the same lift out of it, that's worth more than me keeping it private.

Happy to take questions, PRs, or feedback.

Repo: https://github.com/laggyzee/genesys-mcp

Security note: The OAuth client credentials in this setup connect your MCP server to your tenant. The server runs locally on your machine and stores credentials only in your env vars or a local gitignored .env. Nothing leaves your machine apart from the API calls Claude makes to Genesys on your behalf. Use a dedicated read-only OAuth role per the README - don't reuse a high-privilege client.

Thanks for sharing this, looks really interesting. Keen to try this out 👍

# 1. Clonegit clone https://github.com/laggyzee/genesys-mcpcd genesys-mcp# 2. Create an OAuth Client Credentials client in Genesys Admin#    Required scopes: analytics:readonly, conversations:readonly,#    recordings:readonly, users:readonly, routing:readonly#    Optional: speech-and-text-analytics:readonly, external-contacts:readonly,#    workforce-management:readonly# 3. Set env varscp .env.example ~/.config/genesys-mcp.envchmod 600 ~/.config/genesys-mcp.env# edit and paste your client_id, client_secret, region# 4. Install depsuv sync   # or: pip install -e .# 5. Wire into your MCP client

{  "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"      }    }  }}