mcp-privilege-cloud

CyberArk Privilege Cloud MCP Server

A production-ready Model Context Protocol (MCP) server for comprehensive CyberArk Privilege Cloud integration using the official ark-sdk-python library. Provides complete privileged access management through 53 enterprise-grade MCP tools covering all CyberArk PCloud services with session monitoring capabilities.

Features

• Complete Account Lifecycle: Create, read, update, delete accounts with advanced search and password management (18 tools)
• Comprehensive Safe Operations: Full CRUD operations plus member management with granular permissions (11 tools)
• Platform Management: Complete platform lifecycle including statistics, import/export, and target platform operations (12 tools)
• Applications Management: Full application lifecycle with authentication method management and statistics (9 tools)
• Session Monitoring: Real-time session tracking, activity monitoring, and analytics (6 tools)
• Advanced Analytics: Account filtering, grouping, distribution analysis, and environment categorization
• Enterprise Security: Built on official ark-sdk-python with OAuth, audit logging, and comprehensive error handling
• Production Ready: 160+ passing tests, zero regression, complete API coverage with exact data fidelity

Prerequisites

• Python 3.10+
• CyberArk Privilege Cloud service account

Installation

# Recommended: Install from GitHub repository
uvx --from git+https://github.com/aaearon/mcp-privilege-cloud.git mcp-privilege-cloud

# Development: Clone repository
git clone https://github.com/aaearon/mcp-privilege-cloud.git
cd mcp-privilege-cloud
uv sync

Configuration

Create .env file with required credentials:

CYBERARK_CLIENT_ID=your-service-account-username
CYBERARK_CLIENT_SECRET=your-service-account-password

Test configuration:

python -c "from mcp_privilege_cloud.server import CyberArkMCPServer; import asyncio; server = CyberArkMCPServer.from_environment(); print('Health:', asyncio.run(server.health_check())['status'])"

Usage

Running the Server

# Production
uvx --from git+https://github.com/aaearon/mcp-privilege-cloud.git mcp-privilege-cloud

# Development  
uv run mcp-privilege-cloud

# Module execution
python -m mcp_privilege_cloud

Available Tools (53 Total)

Account Management (18 tools):

• Core Operations: list_accounts, get_account_details, search_accounts, create_account, update_account, delete_account
• Password Management: change_account_password, set_next_password, verify_account_password, reconcile_account_password
• Advanced Search: filter_accounts_by_platform_group, filter_accounts_by_environment, filter_accounts_by_management_status, group_accounts_by_safe, group_accounts_by_platform, analyze_account_distribution, search_accounts_by_pattern, count_accounts_by_criteria

Safe Management (11 tools):

• Core Operations: list_safes, get_safe_details, add_safe, update_safe, delete_safe
• Member Management: list_safe_members, get_safe_member_details, add_safe_member, update_safe_member, remove_safe_member

Platform Management (12 tools):

• Core Operations: list_platforms, get_platform_details, import_platform_package, export_platform
• Lifecycle Management: duplicate_target_platform, activate_target_platform, deactivate_target_platform, delete_target_platform
• Statistics: get_platform_statistics, get_target_platform_statistics

Applications Management (9 tools):

• Core Operations: list_applications, get_application_details, add_application, delete_application
• Auth Methods: list_application_auth_methods, get_application_auth_method_details, add_application_auth_method, delete_application_auth_method
• Statistics: get_applications_stats

Session Monitoring (6 tools):

• Session Management: list_sessions, list_sessions_by_filter, get_session_details, count_sessions
• Activity Tracking: list_session_activities, get_session_statistics

Client Integration

Claude Code

Add the MCP server using the Claude Code CLI:

# Add MCP server from GitHub repository with environment variables
CYBERARK_CLIENT_ID=your-service-account-username CYBERARK_CLIENT_SECRET=your-service-account-password claude mcp add cyberark-privilege-cloud -- uvx --from git+https://github.com/aaearon/mcp-privilege-cloud.git mcp-privilege-cloud

Claude Desktop

Add to your Claude Desktop MCP settings file:

{
  "mcpServers": {
    "cyberark-privilege-cloud": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/aaearon/mcp-privilege-cloud.git",
        "mcp-privilege-cloud"
      ],
      "env": {
        "CYBERARK_CLIENT_ID": "your-service-account-username",
        "CYBERARK_CLIENT_SECRET": "your-service-account-password"
      }
    }
  }
}

Testing with MCP Inspector

Quick Start:

npx @modelcontextprotocol/inspector

Configure with server command uvx --from git+https://github.com/aaearon/mcp-privilege-cloud.git mcp-privilege-cloud and your service account credentials. Should show 53 tools available across all CyberArk PCloud services including session monitoring.

For comprehensive testing procedures, see DEVELOPMENT.md.

Testing

Unit/Integration Tests

# Run all tests
uv run pytest

# Run with coverage  
uv run pytest --cov=mcp_privilege_cloud

# Integration tests
uv run pytest -m integration

MCP Inspector CLI Testing

For programmatic testing and LLM-driven validation:

# Install inspector (one-time setup)
npm install @modelcontextprotocol/inspector

# Test with the single-file testing script
python test_mcp_cli.py health_check      # Server health check
python test_mcp_cli.py list_tools        # List all 53 tools
python test_mcp_cli.py call_tool list_accounts  # Test specific tool
python test_mcp_cli.py generate_report   # Full test report

# Python API for LLMs
from test_mcp_cli import MCPTester
tester = MCPTester()
tools = tester.list_tools()              # Get all tools
health = tester.test_server_health()     # Health check

The test_mcp_cli.py script provides a single-file solution for programmatic MCP server testing, designed for LLM integration and ad-hoc validation.

Troubleshooting

Common Issues:

• Missing environment variables: Create .env file with credentials
• Authentication failed: Verify service account in CyberArk Identity
• Permission errors: Ensure safe permissions for service account
• Connection issues: Verify .cloud domain (not .com)

Quick Health Check:

python -c "from mcp_privilege_cloud.server import CyberArkMCPServer; import asyncio; server = CyberArkMCPServer.from_environment(); print('Status:', asyncio.run(server.health_check())['status'])"

Documentation

• API Reference - Complete tool specifications
• Development Guide - Architecture and contributing
• Testing Guide - Detailed testing instructions

Security

• Never commit credentials to version control
• Use secure environment variable management
• Grant minimal required permissions to service accounts
• Official SDK provides automatic token management and secure protocols

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please use the GitHub Issues page.