cnpg-axians-mcp-server by cuspofaries - MCP Server

CloudNativePG MCP Server by Axians

A Model Context Protocol (MCP) server for managing CloudNativePG PostgreSQL clusters through Claude Desktop and other MCP clients.

Developed by Axians for the Kubernetes and PostgreSQL community.

Features

🚀 Production-Ready PostgreSQL Management

Complete lifecycle management of CloudNativePG clusters with 29 comprehensive tools covering:

Cluster Operations: Create, delete, scale, pause/resume clusters
Backup & Restore: Manual/scheduled backups, point-in-time recovery
High Availability: Primary switchover, replica clusters, replication monitoring
Performance: Connection pooling, metrics, configuration tuning
Security: TLS certificates, authentication management
Advanced Features: PostgreSQL upgrades, extensions, tablespaces, logical replication
Monitoring: Logs, metrics, status monitoring, troubleshooting

🛠 Technical Features

Built with native Kubernetes SDK (no kubectl dependency)
Token-based authentication (secure bearer token)
Cross-namespace operations
Enterprise-grade PostgreSQL management
Real-time cluster monitoring

Installation

For Claude Desktop Users

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "cnpg": {
      "command": "npx",
      "args": ["@cuspofaries/axians-mcp-cnpg-server"],
      "env": {
        "K8S_API_URL": "https://your-k8s-api-server.com",
        "K8S_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

Prerequisites

Node.js 18+
Access to a Kubernetes cluster with CloudNativePG installed
Kubernetes API bearer token

Configuration

Environment Variable	Description	Required
K8S_API_URL	Kubernetes API server URL	Yes
K8S_TOKEN	Bearer token for authentication	Yes

Getting a Bearer Token

# For service account token
kubectl create serviceaccount cnpg-mcp
kubectl get secret $(kubectl get sa cnpg-mcp -o jsonpath='{.secrets[0].name}') -o jsonpath='{.data.token}' | base64 -d

Available Tools (29 Comprehensive Tools)

📋 Cluster Management (5 tools)

list_clusters - List all PostgreSQL clusters across namespaces
get_cluster - Get detailed information about a specific cluster
create_cluster - Create new PostgreSQL clusters with configurable instances, storage, and PostgreSQL version
delete_cluster - Delete PostgreSQL clusters
scale_cluster - Scale cluster to different number of instances

🔄 Backup & Restore Operations (5 tools)

create_backup - Create manual backups of PostgreSQL clusters
list_backups - List backups for clusters or namespaces with filtering
restore_cluster - Create new cluster from existing backup (Point-in-Time Recovery)
get_backup_details - Get detailed information about a specific backup
delete_backup - Delete backups to free up storage space

📊 Monitoring & Troubleshooting (3 tools)

get_cluster_status - Get current status and health of clusters with detailed phase information
get_cluster_pods - Get information about pods in a cluster including readiness, restarts, and roles
get_cluster_events - Get Kubernetes events related to a cluster for troubleshooting

🔧 Advanced Operations (16 tools)

create_scheduled_backup - Set up automated backup schedules with retention policies
list_scheduled_backups - View and manage scheduled backup policies across clusters
get_cluster_logs - Access real-time logs from cluster pods for debugging and monitoring
switchover_primary - Perform controlled primary failover operations for maintenance
get_cluster_metrics - Retrieve Prometheus metrics and performance data
pause_cluster - Hibernate clusters to reduce costs while preserving data
resume_cluster - Wake up hibernated clusters and restore operations
patch_cluster_config - Update PostgreSQL configuration and resource settings live
create_replica_cluster - Set up read replicas and high availability configurations
get_cluster_certificates - Manage and monitor TLS certificates and security settings
create_pooler - Deploy PgBouncer connection pooling for performance optimization
upgrade_postgres_version - Perform in-place PostgreSQL version upgrades safely
get_backup_status - Monitor backup progress and detailed status information
create_logical_replica - Set up logical replication for data synchronization
manage_tablespaces - Configure custom storage locations and performance tuning
create_database_declarative - Provision databases with custom encoding and ownership
get_replication_status - Monitor replication lag and replica health across clusters
manage_extensions - Install and manage PostgreSQL extensions declaratively
set_synchronous_replication - Configure synchronous replication for data consistency

Usage

Simply ask Claude to perform PostgreSQL operations using natural language. Here are comprehensive examples for all 29 tools:

📋 Cluster Management (5 tools)

`list_clusters`

"List all my PostgreSQL clusters"
"Show me all CNPG clusters across all namespaces"
"What PostgreSQL clusters do I have running?"

`get_cluster`

"Get details about the 'production' cluster in the 'db' namespace"
"Show me information about my staging cluster"
"What's the configuration of the main-db cluster?"

`create_cluster`

"Create a new PostgreSQL cluster called 'analytics' with 3 instances and 50Gi storage"
"Set up a development cluster with PostgreSQL 15 and 2 replicas"
"Create a highly available cluster with 5 instances for production workloads"

`delete_cluster`

"Delete the 'test-cluster' in the development namespace"
"Remove the old staging cluster - I don't need it anymore"
"Clean up the temporary cluster we created for testing"

`scale_cluster`

"Scale my production cluster to 7 instances for high availability"
"Reduce the development cluster to 2 instances to save resources"
"Scale up the analytics cluster to handle increased load"

🔄 Backup & Restore Operations (5 tools)

`create_backup`

"Create a backup of my production cluster before the maintenance window"
"Take an immediate backup of the analytics cluster"
"Create a backup named 'pre-migration-backup' for the main database"

`list_backups`

"Show me all backups for the production cluster"
"List backups in the 'database' namespace from the last week"
"What backups do I have available for disaster recovery?"

`restore_cluster`

"Restore a new cluster 'production-restored' from backup 'prod-backup-20241204'"
"Create a new development environment from the latest production backup"
"Restore the analytics cluster to a point-in-time before the data corruption"

`get_backup_details`

"Get detailed information about backup 'prod-backup-20241204'"
"Show me the status and metadata of the latest backup"
"What's the size and completion status of backup-20241205-123456?"

`delete_backup`

"Delete old backup 'staging-backup-20241101' to free up storage space"
"Clean up backups older than 30 days for cost optimization"
"Remove the temporary backup we created for testing"

📊 Monitoring & Troubleshooting (3 tools)

`get_cluster_status`

"Show me the health status of my production cluster"
"What's the current status of all clusters in the database namespace?"
"Check if my cluster is ready and all replicas are healthy"

`get_cluster_pods`

"Show me all pods running in the production cluster"
"What's the status of pods in my staging environment?"
"Which pod is the primary and which are replicas?"

`get_cluster_events`

"Show me recent events for the production cluster to troubleshoot the issue"
"What events occurred when my cluster failed to start?"
"Get Kubernetes events for debugging the database connection problems"

🔧 Advanced Operations (16 tools)

`create_scheduled_backup`

"Set up daily backups for the production cluster at 2 AM with 30-day retention"
"Create a weekly backup schedule for the analytics cluster every Sunday"
"Configure automated backups every 6 hours for the critical database"

`list_scheduled_backups`

"Show me all scheduled backup policies across all clusters"
"List backup schedules for the production namespace"
"What automated backups are configured for my databases?"

`get_cluster_logs`

"Show me the latest logs from the production cluster primary pod"
"Get error logs from the last 100 lines of the database cluster"
"Display PostgreSQL logs from the analytics cluster for debugging"

`switchover_primary`

"Perform a controlled failover for the production cluster maintenance"
"Switch the primary to the replica in zone-b for load balancing"
"Initiate primary switchover to test high availability"

`get_cluster_metrics`

"Show me performance metrics for the production cluster"
"Get CPU and memory usage statistics for all database pods"
"Display Prometheus metrics for monitoring dashboard"

`pause_cluster`

"Hibernate the development cluster to save costs over the weekend"
"Pause the testing cluster - we'll resume it on Monday"
"Put the staging environment in hibernation mode"

`resume_cluster`

"Wake up the development cluster for the new sprint"
"Resume the hibernated testing cluster for QA validation"
"Bring the staging environment back online"

`patch_cluster_config`

"Update the production cluster to use more memory and enable query logging"
"Modify PostgreSQL parameters for better performance tuning"
"Change the cluster configuration to increase connection limits"

`create_replica_cluster`

"Set up a read replica cluster in the DR region from production"
"Create a replica cluster for reporting workloads to offload the primary"
"Deploy a cross-region replica for disaster recovery"

`get_cluster_certificates`

"Show me the TLS certificates for the production cluster"
"List all SSL certificates and their expiration dates"
"Check certificate status for secure database connections"

`create_pooler`

"Deploy PgBouncer connection pooling for the production cluster"
"Set up a connection pool with session mode for web applications"
"Create a pooler with 100 max connections for high-traffic scenarios"

`upgrade_postgres_version`

"Upgrade the production cluster to PostgreSQL 16 safely"
"Update the development cluster to the latest PostgreSQL version"
"Perform a rolling upgrade to PostgreSQL 15.4"

`get_backup_status`

"Check the progress of the backup 'prod-backup-20241205-143022'"
"Show me detailed status of the currently running backup"
"Monitor the backup completion and verify integrity"

`create_logical_replica`

"Set up logical replication from production to the analytics cluster"
"Create a logical replica for real-time data synchronization"
"Configure logical replication for selective table replication"

`manage_tablespaces`

"Add a fast SSD tablespace to the production cluster for indexes"
"Create a separate tablespace for archive data on slower storage"
"Configure custom tablespaces for performance optimization"

`create_database_declarative`

"Create a new 'analytics' database with UTF8 encoding owned by analyst_user"
"Add a database for the new microservice with specific collation"
"Set up a database for the reporting application"

`get_replication_status`

"Check replication lag between primary and all replicas"
"Show me the health status of streaming replication"
"Monitor replica synchronization across all clusters"

`manage_extensions`

"Install PostGIS and pg_stat_statements extensions on the analytics cluster"
"Enable the pgcrypto extension for encryption capabilities"
"Add TimescaleDB extension for time-series data"

`set_synchronous_replication`

"Enable synchronous replication for the production cluster for data consistency"
"Configure synchronous replication with 2 replicas for critical data"
"Set up sync replication to prevent data loss during failures"

💡 Pro Tips for Usage

Combine operations: "Create a backup, then scale my cluster to 5 instances"
Use specific names: "Show metrics for the 'ecommerce-prod' cluster in 'production' namespace"
Context-aware requests: "Before upgrading PostgreSQL, create a backup and check cluster health"
Monitoring workflows: "Check cluster status, then show me any error events from the last hour"

Examples

Basic Usage

# Test the server locally
npx @cuspofaries/axians-mcp-cnpg-server

Advanced Configuration

{
  "mcpServers": {
    "cnpg-production": {
      "command": "npx",
      "args": ["@cuspofaries/axians-mcp-cnpg-server"],
      "env": {
        "K8S_API_URL": "https://prod-k8s.company.com",
        "K8S_TOKEN": "prod_token_here"
      }
    },
    "cnpg-staging": {
      "command": "npx", 
      "args": ["@cuspofaries/axians-mcp-cnpg-server"],
      "env": {
        "K8S_API_URL": "https://staging-k8s.company.com",
        "K8S_TOKEN": "staging_token_here"
      }
    }
  }
}

Troubleshooting

Common Issues

Authentication errors: Verify your K8S_TOKEN has proper RBAC permissions
Connection refused: Check K8S_API_URL is accessible from your machine
No clusters found: Ensure CloudNativePG is installed in your cluster

Required RBAC permissions

For full functionality with all 29 tools:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: cnpg-mcp-server
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cnpg-mcp-manager
rules:
# CloudNativePG Resources (Full Management)
- apiGroups: ["postgresql.cnpg.io"]
  resources: ["clusters", "backups", "scheduledbackups", "poolers"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
# Kubernetes Core Resources
- apiGroups: [""]
  resources: ["pods", "pods/log", "secrets", "namespaces"]
  verbs: ["get", "list", "watch"]
# Additional permissions for advanced features
- apiGroups: [""]
  resources: ["persistentvolumeclaims"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cnpg-mcp-server-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cnpg-mcp-manager
subjects:
- kind: ServiceAccount
  name: cnpg-mcp-server
  namespace: default
---
# Token secret for authentication
apiVersion: v1
kind: Secret
metadata:
  name: cnpg-mcp-server-token
  namespace: default
  annotations:
    kubernetes.io/service-account.name: cnpg-mcp-server
type: kubernetes.io/service-account-token

🔒 Read-Only RBAC (for monitoring/viewing only)

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cnpg-mcp-reader
rules:
- apiGroups: ["postgresql.cnpg.io"]
  resources: ["clusters", "backups", "scheduledbackups", "poolers"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["pods", "pods/log", "secrets", "namespaces"]
  verbs: ["get", "list", "watch"]

Development

git clone https://github.com/cuspofaries/cnpg-axians-mcp-server.git
cd cnpg-axians-mcp-server
npm install
npm run build
npm start

Contributing

We welcome contributions! Please see our Contributing Guide.

About Axians

This project is developed by Axians, a VINCI Energies brand, specializing in ICT solutions and services.

Support

Report Issues: https://github.com/cuspofaries/cnpg-axians-mcp-server/issues
Discussions: https://github.com/cuspofaries/cnpg-axians-mcp-server/discussions
Email: anthony.macle@axians.com

License

MIT