Guepard MCP Server - Complete API Implementation

A comprehensive Model Context Protocol (MCP) server for the Guepard database management platform, providing access to all Guepard APIs through organized modules.

🚀 Quick Start

Using Docker Hub Image

# Pull the image
docker pull mghassen/guepard-custom-mcp:latest

# Run the MCP server
docker run --rm -i -e ACCESS_TOKEN="your_guepard_token" mghassen/guepard-custom-mcp:latest

Using with Cursor

Add this to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "guepard": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "ACCESS_TOKEN=your_guepard_token", "mghassen/guepard-custom-mcp:latest"],
      "env": {}
    }
  }
}

Local Development

# Clone the repository
git clone <repository-url>
cd guepard-mcp-server

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export ACCESS_TOKEN="your_guepard_token"
export GUEPARD_API_URL="https://api.guepard.run"
export GUEPARD_AUTH_API="https://auth.guepard.run"
export SUPABASE_ANON_KEY="your_supabase_key"

# Run the server
python main.py

🛠️ Available Tools

The MCP server provides comprehensive access to all Guepard APIs through organized modules:

🔐 Authentication

• login_supabase - Login with Supabase authentication
• refresh_token_supabase - Refresh access token with Supabase
• logout_supabase - Logout and invalidate tokens with Supabase

🚀 Deployments

• list_deployments - Get all deployments (with optional filtering)
• create_deployment - Create a new database deployment
• get_deployment - Get deployment details
• update_deployment - Update deployment
• delete_deployment - Delete deployment

🌿 Branches

• list_branches - Get branches for deployment
• create_branch_from_snapshot - Create a new branch from snapshot
• update_branch - Update branch

🔄 Checkouts

• checkout_branch - Checkout to a specific snapshot
• checkout_snapshot - Checkout to a random snapshot from deployment

📸 Snapshots

• create_snapshot - Create a snapshot
• list_snapshots_deployment - Get snapshots for deployment
• list_snapshots_branch - Get snapshots for branch

🏗️ Shadows

• list_shadows_for_deployment - List shadow deployments for a specific deployment
• list_all_shadows - List all shadow deployments
• create_shadow - Create a new shadow deployment from a snapshot

🖥️ Nodes

• list_nodes - Get all nodes
• create_node - Create a new node
• get_node - Get node details

⚡ Performance Profiles

• list_performance_profiles - Get all performance profiles
• create_performance_profile - Create performance profile
• update_performance_profile - Update performance profile
• apply_performance_profile - Apply performance profile to deployment

💻 Compute

• get_compute_status - Get compute status
• get_compute - Get compute information
• start_compute - Start compute for a deployment
• stop_compute - Stop compute for a deployment

📊 Logs & Metrics

• get_deployment_logs - Get deployment logs
• get_deployment_metrics - Get deployment metrics

👥 Database Users

• list_database_users - Get database users for deployment
• create_database_user - Create database user
• update_database_user - Update database user
• delete_database_user - Delete database user
• grant_privileges - Grant privileges to database user
• revoke_privileges - Revoke privileges from database user
• list_user_privileges - List privileges for database user

🔑 Tokens

• list_tokens - Get all tokens
• generate_token - Generate new token
• revoke_token - Revoke token

📡 Notifications & Subscriptions

• subscribe_deployment - Subscribe to deployment notifications
• unsubscribe_deployment - Unsubscribe from deployment notifications
• list_subscriptions - List all deployment subscriptions
• manage_subscriptions - Manage multiple deployment subscriptions

🛠️ Utilities

• test_connection - Test connection to Guepard API
• list_configurations - List available predefined configurations
• get_configuration - Get current server configuration

📋 Prerequisites

• Docker installed and running (for Docker usage)
• Python 3.12+ (for local development)
• Valid Guepard access token
• Cursor IDE (for MCP integration)

🔧 Configuration

Environment Variables

Required:

• ACCESS_TOKEN: Your Guepard platform access token

Optional:

• GUEPARD_API_URL: Guepard API base URL (defaults to https://api.guepard.run)
• GUEPARD_AUTH_API: Guepard auth API URL (defaults to https://auth.guepard.run)
• SUPABASE_ANON_KEY: Supabase anonymous key for authentication
• POSTGRES16_PROFILE_ID: Performance profile ID for PostgreSQL 16
• POSTGRES17_PROFILE_ID: Performance profile ID for PostgreSQL 17

Tool Activation (New!):

• GUEPARD_CONFIG: Use predefined configuration (minimal, read_only, production, development, monitoring)
• GUEPARD_ENABLED_MODULES: Comma-separated list of modules to enable
• GUEPARD_ENABLED_TOOLS: Comma-separated list of specific tools to enable
• GUEPARD_DISABLED_TOOLS: Comma-separated list of tools to disable
• GUEPARD_DISABLED_MODULES: Comma-separated list of modules to disable

Example Usage

# Test the connection (all tools enabled)
docker run --rm -i -e ACCESS_TOKEN="your_token" mghassen/guepard-custom-mcp:latest

# Use predefined configuration (minimal tools)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_CONFIG="minimal" mghassen/guepard-custom-mcp:latest

# Use predefined configuration (read-only)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_CONFIG="read_only" mghassen/guepard-custom-mcp:latest

# Use predefined configuration (production-safe)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_CONFIG="production" mghassen/guepard-custom-mcp:latest

# Custom configuration (specific tools only)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_ENABLED_TOOLS="test_connection,list_deployments,get_deployment,start_compute,stop_compute" mghassen/guepard-custom-mcp:latest

# In Cursor, ask:
# "Test my Guepard connection"
# "Get all my deployments"
# "Create a new deployment with PostgreSQL 17"
# "Start compute for deployment xyz"
# "Create a database user with specific privileges"
# "List available configurations"
# "Get current configuration"

⚙️ Tool Activation & Configuration

The Guepard MCP Server now supports selective activation of tools and modules, allowing you to build custom configurations for different use cases.

🚀 Predefined Configurations

🛠️ Custom Configuration Examples

# Enable only specific modules
docker run --rm -i \
  -e ACCESS_TOKEN="your_token" \
  -e GUEPARD_ENABLED_MODULES="deployments,compute" \
  mghassen/guepard-custom-mcp:latest

# Enable only specific tools
docker run --rm -i \
  -e ACCESS_TOKEN="your_token" \
  -e GUEPARD_ENABLED_TOOLS="test_connection,list_deployments,get_deployment,start_compute,stop_compute" \
  mghassen/guepard-custom-mcp:latest

# Disable dangerous operations
docker run --rm -i \
  -e ACCESS_TOKEN="your_token" \
  -e GUEPARD_DISABLED_TOOLS="delete_deployment,delete_database_user,revoke_token" \
  mghassen/guepard-custom-mcp:latest

🔍 Configuration Verification

Use the built-in tools to verify your configuration:

• list_configurations - List all available predefined configurations
• get_configuration - Get current server configuration details

🏗️ Project Structure

guepard-mcp-server/
├── src/
│   └── guepard_mcp/
│       ├── auth/           # Authentication tools
│       ├── deployments/   # Deployment management
│       ├── branches/       # Branch management
│       ├── snapshots/      # Snapshot management
│       ├── shadows/        # Shadow deployment management
│       ├── nodes/          # Node management
│       ├── performance/    # Performance profiles
│       ├── compute/        # Compute management
│       ├── users/          # Database users
│       ├── tokens/         # Token management
│       ├── utils/          # Base classes and utilities
│       └── server.py       # Main server implementation
├── main.py                 # Entry point
├── requirements.txt        # Python dependencies
├── Dockerfile             # Docker configuration
└── README.md              # This file

🐳 Docker Images

• mghassen/guepard-custom-mcp:latest - Latest version
• mghassen/guepard-custom-mcp:2.0.0 - Stable version 2.0.0

🔍 Troubleshooting

Common Issues

1. "ACCESS_TOKEN is required"

   • Make sure you've set the ACCESS_TOKEN environment variable
   • Verify your token is valid

2. "No tools available in Cursor"

   • Restart Cursor after updating mcp.json
   • Check that Docker is running
   • Verify the image is pulled: docker pull mghassen/guepard-custom-mcp:latest

3. Connection issues

   • Test the connection first: docker run --rm -i -e ACCESS_TOKEN="your_token" mghassen/guepard-custom-mcp:latest
   • Check your internet connection
   • Verify your Guepard credentials are valid

4. Authentication errors

   • Ensure SUPABASE_ANON_KEY is set for auth operations
   • Verify GUEPARD_AUTH_API is correct

Debug Mode

Run with debug logging:

docker run --rm -i -e ACCESS_TOKEN="your_token" -e DEBUG=true mghassen/guepard-custom-mcp:latest

📚 API Reference

Tool Parameters

Authentication Tools

• login_supabase: email (required), password (required)
• refresh_token_supabase: refresh_token (required)
• logout_supabase: refresh_token (required)

Deployment Tools

• list_deployments: status (optional), limit (optional)
• create_deployment: repository_name (required), performance_profile_id (required), plus optional fields
• get_deployment: deployment_id (required)
• update_deployment: deployment_id (required), plus fields to update
• delete_deployment: deployment_id (required)

Branch Tools

• list_branches: deployment_id (required)
• create_branch_from_snapshot: deployment_id, branch_id, snapshot_id, branch_name (all required), is_ephemeral (optional)
• update_branch: deployment_id, branch_id (required), plus fields to update

Checkout Tools

• checkout_branch: deployment_id, branch_id, snapshot_id (all required)
• checkout_snapshot: deployment_id (required), plus optional parameters

Snapshot Tools

• create_snapshot: deployment_id, branch_id, snapshot_comment (all required)
• list_snapshots_deployment: deployment_id (required)
• list_snapshots_branch: deployment_id, branch_id (both required)

Shadow Tools

• list_shadows_for_deployment: deployment_id (required)
• list_all_shadows: No parameters
• create_shadow: deployment_id, snapshot_id, repository_name, branch_name, performance_profile_id (all required)

Node Tools

• list_nodes: No parameters
• create_node: label_name, node_type, memory, cpu, storage (required), plus optional fields
• get_node: node_id (required)

Performance Profile Tools

• list_performance_profiles: No parameters
• create_performance_profile: label_name, min_cpu, min_memory (required), plus optional fields
• update_performance_profile: performance_profile_id (required), plus fields to update
• apply_performance_profile: deployment_id, performance_profile_id (both required)

Compute Tools

• get_compute_status: deployment_id (required)
• get_compute: deployment_id (required)
• start_compute: deployment_id (required), notify (optional)
• stop_compute: deployment_id (required), notify (optional)

Logs & Metrics Tools

• get_deployment_logs: deployment_id (required), lines (optional), level (optional), component (optional)
• get_deployment_metrics: deployment_id (required), time_range (optional), metric_type (optional)

Database User Tools

• list_database_users: deployment_id (required)
• create_database_user: deployment_id, username, password (required), privileges (optional)
• update_database_user: deployment_id, username (required), password (optional)
• delete_database_user: deployment_id, username (required)
• grant_privileges: deployment_id, username, privileges (all required)
• revoke_privileges: deployment_id, username, privileges (all required)
• list_user_privileges: deployment_id, username (both required)

Token Tools

• list_tokens: No parameters
• generate_token: name (required), expires_in (optional)
• revoke_token: token_id (required)

Notification & Subscription Tools

• subscribe_deployment: deployment_id (required)
• unsubscribe_deployment: deployment_id (required)
• list_subscriptions: No parameters
• manage_subscriptions: action (required), deployment_ids (required)

Utility Tools

• test_connection: No parameters
• list_configurations: No parameters
• get_configuration: No parameters

🆘 Support

• Issues: Report issues on GitHub
• Documentation: Check the main README.md
• Guepard Platform: Visit guepard.run

📄 License

MIT License - see LICENSE file for details.

Ready to use! Pull the image and start managing your Guepard deployments with Cursor! 🎉