guepard-mcp-server
No description available
Ask AI about guepard-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about guepard-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 authenticationrefresh_token_supabase- Refresh access token with Supabaselogout_supabase- Logout and invalidate tokens with Supabase
π Deployments
list_deployments- Get all deployments (with optional filtering)create_deployment- Create a new database deploymentget_deployment- Get deployment detailsupdate_deployment- Update deploymentdelete_deployment- Delete deployment
πΏ Branches
list_branches- Get branches for deploymentcreate_branch_from_snapshot- Create a new branch from snapshotupdate_branch- Update branch
π Checkouts
checkout_branch- Checkout to a specific snapshotcheckout_snapshot- Checkout to a random snapshot from deployment
πΈ Snapshots
create_snapshot- Create a snapshotlist_snapshots_deployment- Get snapshots for deploymentlist_snapshots_branch- Get snapshots for branch
ποΈ Shadows
list_shadows_for_deployment- List shadow deployments for a specific deploymentlist_all_shadows- List all shadow deploymentscreate_shadow- Create a new shadow deployment from a snapshot
π₯οΈ Nodes
list_nodes- Get all nodescreate_node- Create a new nodeget_node- Get node details
β‘ Performance Profiles
list_performance_profiles- Get all performance profilescreate_performance_profile- Create performance profileupdate_performance_profile- Update performance profileapply_performance_profile- Apply performance profile to deployment
π» Compute
get_compute_status- Get compute statusget_compute- Get compute informationstart_compute- Start compute for a deploymentstop_compute- Stop compute for a deployment
π Logs & Metrics
get_deployment_logs- Get deployment logsget_deployment_metrics- Get deployment metrics
π₯ Database Users
list_database_users- Get database users for deploymentcreate_database_user- Create database userupdate_database_user- Update database userdelete_database_user- Delete database usergrant_privileges- Grant privileges to database userrevoke_privileges- Revoke privileges from database userlist_user_privileges- List privileges for database user
π Tokens
list_tokens- Get all tokensgenerate_token- Generate new tokenrevoke_token- Revoke token
π‘ Notifications & Subscriptions
subscribe_deployment- Subscribe to deployment notificationsunsubscribe_deployment- Unsubscribe from deployment notificationslist_subscriptions- List all deployment subscriptionsmanage_subscriptions- Manage multiple deployment subscriptions
π οΈ Utilities
test_connection- Test connection to Guepard APIlist_configurations- List available predefined configurationsget_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 authenticationPOSTGRES16_PROFILE_ID: Performance profile ID for PostgreSQL 16POSTGRES17_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 enableGUEPARD_ENABLED_TOOLS: Comma-separated list of specific tools to enableGUEPARD_DISABLED_TOOLS: Comma-separated list of tools to disableGUEPARD_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
| Configuration | Description | Use Case |
|---|---|---|
minimal | Minimal deployment management only | Basic operations |
read_only | Read-only access to deployments and monitoring | Monitoring dashboards |
production | Production environment without dangerous operations | Production deployments |
development | Full development environment with all tools | Development work |
monitoring | Monitoring and observability only | System monitoring |
π οΈ 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 configurationsget_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 versionmghassen/guepard-custom-mcp:2.0.0- Stable version 2.0.0
π Troubleshooting
Common Issues
-
"ACCESS_TOKEN is required"
- Make sure you've set the ACCESS_TOKEN environment variable
- Verify your token is valid
-
"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
-
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
- Test the connection first:
-
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 fieldsget_deployment:deployment_id(required)update_deployment:deployment_id(required), plus fields to updatedelete_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 parameterscreate_shadow:deployment_id,snapshot_id,repository_name,branch_name,performance_profile_id(all required)
Node Tools
list_nodes: No parameterscreate_node:label_name,node_type,memory,cpu,storage(required), plus optional fieldsget_node:node_id(required)
Performance Profile Tools
list_performance_profiles: No parameterscreate_performance_profile:label_name,min_cpu,min_memory(required), plus optional fieldsupdate_performance_profile:performance_profile_id(required), plus fields to updateapply_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 parametersgenerate_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 parametersmanage_subscriptions:action(required),deployment_ids(required)
Utility Tools
test_connection: No parameterslist_configurations: No parametersget_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! π
