Genesys Cloud MCP Plus

🚀 Advanced Model Context Protocol Server for Genesys Cloud

A comprehensive MCP server providing 15 powerful tools for contact center analytics, real-time monitoring, and intelligent conversation analysis. Designed for enterprise-grade AI applications with full omnichannel support.

🌟 Features

📊 Historical Analytics (8 Tools)

• Queue Volume Analysis - Compare conversation volumes across queues
• Conversation Sampling - Retrieve representative conversation samples
• Voice Call Quality - Analyze MOS scores and call quality metrics
• Conversation Sentiment - Sentiment analysis across interactions
• Conversation Topics - Extract business topics and intents
• Conversation Transcripts - Full conversation transcripts with timestamps
• Enhanced Media Search - Multi-channel conversation discovery
• Agent Performance Analytics - Media-type breakdown of agent metrics

⚡ Real-Time Monitoring (3 Tools)

• Live Queue Status - Real-time queue metrics and agent availability
• Agent Presence Monitoring - Current agent status and routing state
• Active Conversation Tracking - Monitor ongoing customer interactions

🏷️ Wrap-Up Code Analytics (1 Tool)

• Comprehensive Wrap-Up Analysis - Understand interaction types and volumes
• Multi-language Support - Handles Arabic/English bilingual environments
• Queue-specific Filtering - Targeted analysis by queue or service area

🔍 Utility Tools (3 Tools)

• Queue Search - Find queues by name with wildcard support
• Agent Directory - Monitor agent information and status
• Enhanced Conversation Search - Advanced filtering across all media types

📋 Supported Media Types

• 📞 Voice calls
• 💬 Chat interactions
• 📧 Email conversations
• 📱 SMS/Text messaging
• 🤖 Bot interactions
• 📹 Video calls
• 🌐 Social media interactions
• 📞 Callback requests

🛠️ Installation

NPM Installation

npm install -g genesys-cloud-mcp-plus

Manual Installation

git clone https://github.com/AmrKhalil9/genesys-cloud-mcp-plus.git
cd genesys-cloud-mcp-plus
npm install
npm run build

⚙️ Configuration

Environment Variables

export GENESYSCLOUD_REGION="your-region"  # e.g., "eu-central-1", "me-central-1", "us-east-1"
export GENESYSCLOUD_OAUTHCLIENT_ID="your-client-id"
export GENESYSCLOUD_OAUTHCLIENT_SECRET="your-client-secret"

Region Examples:

• UAE/Middle East: me-central-1
• EMEA: eu-central-1
• Americas: us-east-1
• Australia: ap-southeast-2
• Japan: ap-northeast-1

Supported Regions

🌎 Americas (5 Regions)

• us-east-1 → mypurecloud.com (Americas - Main)
• us-east-2 → use2.us-gov-pure.cloud (FedRAMP - US Government)
• us-west-2 → usw2.pure.cloud (US West)
• ca-central-1 → cac1.pure.cloud (Canada)
• sa-east-1 → sae1.pure.cloud (South America)

🌍 Europe, Middle East, Africa (5 Regions)

• eu-central-1 → mypurecloud.de (EMEA - Main)
• eu-west-1 → mypurecloud.ie (Ireland)
• eu-west-2 → euw2.pure.cloud (Europe West 2)
• eu-central-2 → euc2.pure.cloud (Europe Central 2)
• me-central-1 → mec1.pure.cloud (Middle East - UAE)

🌏 Asia Pacific (5 Regions)

• ap-southeast-2 → mypurecloud.com.au (Australia)
• ap-northeast-1 → mypurecloud.jp (Japan)
• ap-south-1 → aps1.pure.cloud (Asia Pacific South)
• ap-northeast-2 → apne2.pure.cloud (Asia Pacific Northeast 2)
• ap-northeast-3 → apne3.pure.cloud (Asia Pacific Northeast 3)

Total: 15 Regions - Full global coverage including UAE/Middle East support!

OAuth Permissions Required

Your OAuth client needs these permissions:

• analytics:conversationAggregate:view
• analytics:conversationDetail:view
• routing:queue:view
• users:basic:view
• presence:basic:view
• speechandtextanalytics:data:view

🚀 Usage

Claude Desktop Integration

Method 1: Global Installation (Recommended)

First install globally:

npm install -g genesys-cloud-mcp-plus

Then add to your claude_desktop_config.json:

{
  "mcpServers": {
    "genesys-cloud-mcp-plus": {
      "type": "stdio",
      "command": "genesys-cloud-mcp-plus",
      "env": {
        "GENESYSCLOUD_REGION": "eu-central-1",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "<PUT OAUTHCLIENT ID HERE>",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "<PUT OAUTHCLIENT SECRET HERE>"
      }
    }
  }
}

Method 2: NPX (No Installation Required)

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "genesys-cloud-mcp-plus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "genesys-cloud-mcp-plus"],
      "env": {
        "GENESYSCLOUD_REGION": "eu-central-1",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "<PUT OAUTHCLIENT ID HERE>",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "<PUT OAUTHCLIENT SECRET HERE>"
      }
    }
  }
}

Configuration Examples by Region:

• UAE/Middle East: "GENESYSCLOUD_REGION": "me-central-1"
• EMEA: "GENESYSCLOUD_REGION": "eu-central-1"
• Americas: "GENESYSCLOUD_REGION": "us-east-1"
• Australia: "GENESYSCLOUD_REGION": "ap-southeast-2"
• Japan: "GENESYSCLOUD_REGION": "ap-northeast-1"
• FedRAMP: "GENESYSCLOUD_REGION": "us-east-2"

Complete Example Configuration:

{
  "mcpServers": {
    "genesys-cloud-mcp-plus": {
      "type": "stdio",
      "command": "genesys-cloud-mcp-plus",
      "env": {
        "GENESYSCLOUD_REGION": "me-central-1",
        "GENESYSCLOUD_OAUTHCLIENT_ID": "29aa13c7-1693-47dc-8672-fb502990971c",
        "GENESYSCLOUD_OAUTHCLIENT_SECRET": "bCoYOs1qeOcXjDfwQM6XVA-kfYIl0wYiLyLVrbj7IAc"
      }
    }
  }
}

Quick Setup Guide

1. Install the package:

   npm install -g genesys-cloud-mcp-plus

2. Get your Genesys Cloud credentials:

   • Go to Genesys Cloud Admin → Integrations → OAuth
   • Create a new OAuth client with required permissions
   • Copy the Client ID and Client Secret

3. Configure Claude Desktop:

   • Open claude_desktop_config.json
   • Add the MCP server configuration (see examples above)
   • Replace placeholders with your actual credentials

4. Restart Claude Desktop and start exploring your data!

Command Line

# Start the MCP server
genesys-cloud-mcp-plus

# Development mode
npm run dev

# Build for production
npm run build

📚 Tool Reference

Historical Analytics

| Tool | Purpose | Use Case | |------|---------|----------| | search_queues | Find queues by name | "Find all sales queues" | | query_queue_volumes | Compare queue volumes | "Which queue is busiest today?" | | sample_conversations_by_queue | Get conversation samples | "Show me recent support calls" | | voice_call_quality | Analyze call quality | "Check call quality for conversation X" | | conversation_sentiment | Sentiment analysis | "What's the sentiment of these calls?" | | conversation_topics | Topic detection | "What topics were discussed?" | | conversation_transcript | Full transcripts | "Get transcript for conversation X" | | enhanced_conversation_search | Multi-media search | "Find all chat conversations today" |

Real-Time Monitoring

| Tool | Purpose | Use Case | |------|---------|----------| | real_time_queue_status | Live queue metrics | "How many agents are available?" | | real_time_agent_presence | Agent status monitoring | "Who's online right now?" | | live_conversation_monitoring | Active interactions | "What conversations are happening?" |

Analytics & Insights

| Tool | Purpose | Use Case | |------|---------|----------| | wrap_up_code_analytics | Interaction type analysis | "How many inquiries came today?" | | agent_media_type_performance | Agent performance by channel | "How is John performing on chat?" | | agent_status_monitoring | Agent directory | "Show me all active agents" | | search_voice_conversations | Voice-specific search | "Find voice calls from this number" |

🔍 Example Queries

Business Intelligence

"What were the top 3 wrap-up codes for our support queue this week?"
"Which agents handled the most chat conversations yesterday?"
"Show me sentiment analysis for all conversations from customer X"

Operations Monitoring

"How many agents are currently available?"
"What conversations are active right now?"
"Which queue has the longest wait times?"

Quality Assurance

"Find conversations with poor call quality scores"
"What topics are customers asking about most?"
"Show me transcripts from escalated calls"

🛡️ Enterprise Features

• 🔒 Secure Authentication - OAuth 2.0 with client credentials
• 🌍 Multi-Region Support - Works with all Genesys Cloud regions
• 🗣️ Multi-Language - Supports bilingual environments (Arabic/English)
• 📊 Comprehensive Analytics - 15 different analytical perspectives
• ⚡ Real-Time Data - Live monitoring capabilities
• 🔧 Production Ready - Error handling, logging, and retry logic

📖 Documentation

• AI Agent Guide - Complete guide for AI implementations
• Changelog - Version history and new features
• API Reference - Detailed tool documentation

👥 Authors & Contributors

Original Author

Lucas Woodward - MakingChatbots.com

• Created the foundational MCP server with 8 core analytics tools
• Established the original architecture and Genesys Cloud integration

Enhanced Version

Amr Khalil

• Added 7 new tools including real-time monitoring and wrap-up code analytics
• Enhanced existing tools with improved error handling and performance
• Transformed basic server into comprehensive enterprise-grade platform

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📝 License

ISC License - see LICENSE for details.

🔗 Links

• GitHub Repository
• NPM Package
• MakingChatbots.com

📞 Support

For issues, questions, or feature requests:

• GitHub Issues: Report here
• Documentation: Check the AI Agent Guide for implementation details

Built with ❤️ for the AI and Contact Center Community