Managing Clusters using ClusterControl MCP

In this section, we explore how to manage your database clusters using natural language through the ClusterControl MCP Server. Instead of navigating dashboards or running CLI commands, you simply describe what you want to your AI assistant and it handles the rest.

If you haven't set up the ClusterControl MCP Server yet, please go through the ClusterControl MCP documentation first before continuing.

If you have already installed and integrated it with your AI assistant, make sure the integration is working properly before proceeding. For example, if you are using Claude Desktop, go to Settings 🡒 Developer and confirm that the ClusterControl MCP is listed and running. See screenshot below

Once you can see the MCP Server is running, you are ready to start managing your clusters. The examples below cover the most common operations you can perform through your AI assistant.

Any action that changes something like creating a job, adding a user, scheduling maintenance, restoring a backup, setting node or controller config, etc. Works in two steps:

Dry run (default): AI Assistants describes exactly what it would do, without touching your CMON controller.
Execute: After you confirm, AI Assistants calls the tool again with dry_run=false to carry out the action.

High-risk operations (node restart, failover, drop cluster, drop user, delete backup schedule, restore backup, delete ClusterControl account) include an additional warning in the dry-run output so nothing destructive ever runs without your explicit approval.

User and Access Management

Manage database accounts, review privileges, create or revoke access across your clusters.

List Functions

Below are the functions that currently supported by clustercontrol-mcp for User and Access Management.

Function	Purpose
`list_db_users`	List all database accounts on a cluster (Required Cluster ID)
`create_db_user`	Create a new database user account (Required Cluster ID)
`drop_db_user`	Delete a database user account (Required Cluster ID)
`grant_db_user`	Grant privileges to a database user (Required Cluster ID)
`revoke_db_user`	Revoke specific privileges from a database user (Required Cluster ID)
`revoke_all_db_user`	Revoke all privileges from a database user (Required Cluster ID)
`list_cmon_users`	List all ClusterControl controller user accounts (Required Cluster ID)
`list_cmon_groups`	List all ClusterControl controller user groups (Required Cluster ID)
`create_cmon_user`	Create a new ClusterControl controller user account (Required Cluster ID)
`set_cmon_user`	Modify a ClusterControl controller user profile (Required Cluster ID)
`drop_cmon_user`	Delete a ClusterControl controller user account (Required Cluster ID)

Example Prompt

Here are some examples of using clustercontrol-mcp for User and Access Management:

List existing users and groups using prompt

List all users and groups that exists in clustercontrol and mask the email
Create ClusterControl user and attach to group using prompt

Create a Clustercontrol user with username support and email [email protected] using password severalNINES999 in group admins

Cluster Inventory and Health

Get a complete picture of your clusters, nodes, topology, and active alarms.

List Functions

Function	Purpose
`list_clusters`	Full fleet overview with cluster types, states, and versions
`get_cluster`	Detailed view of a specific cluster including all hosts and their roles (Required Cluster ID)
`get_cluster_topology`	Normalized topology view showing nodes and replication links (Required Cluster ID)
`list_nodes`	Flattened node inventory across all clusters or one cluster (Optional Cluster ID)
`list_alarms`	Active alarms for a specific cluster (Required Cluster ID)
`list_all_alarms`	Active alarms across the entire fleet
`get_controller_info`	CMON version, RPC version, and connectivity status
`get_cluster_logs`	Contents of one collected log file, addressed by (cluster_id, hostname, filename). Tail of last 200 lines by default; optional output_path writes the full file locally (Required Cluster ID)
`get_cmon_logs`	CMON daemon log entries for a cluster. New optional filters: severity, component, hostname, since
`get_cmon_log_statistics`	Summary counts of CMON log entries by severity and component
`list_cluster_logs`	Inventory of log files CMON has collected from cluster hosts (mysqld.log, postgresql-*.log, prometheus.log, agent_internal_logs.log, cmnd.log)

Example Prompt

Here are some examples of using clustercontrol-mcp for Cluster Inventory and Health:

Get information about Cluster databases

List all database clusters

Get details for cluster cluster_id or cluster_name

Get the logs for cluster cluster_id or cluster_name

List active alarms for cluster cluster_id or cluster_name

Performance Analysis

Identify slow queries, long-running transactions, deadlocks, and other performance bottlenecks across your database fleet.

List Functions

Function	Purpose
`get_cluster_stats`	Time-series CPU, memory, disk, network, SQL, and DB stats (Required Cluster ID)
`get_top_queries`	Top resource-consuming query digests (Required Cluster ID)
`get_sql_processes`	Live process list across all nodes (Required Cluster ID)
`kill_db_process`	Terminate runaway queries (Required Cluster ID)
`get_db_growth`	Historical database size trends for capacity planning (Required Cluster ID)
`check_no_primary_keys`	Find tables missing a primary key (Required Cluster ID)
`check_redundant_indexes`	Find redundant indexes (Required Cluster ID)
`check_myisam_tables`	Find tables using the MyISAM storage engine (Required Cluster ID)
`get_tx_deadlocks`	Transaction deadlock analysis with blocking SQL

Example Prompt

Here are some examples of using clustercontrol-mcp for Performance Analysis:

Show current processlist from the cluster.

Show currently running SQL queries on cluster mariasn (mariadb)
Kill the running job

Kill the query with pid #14927

Jobs and Operations

Monitor running and completed jobs, track task progress, and review operational history across your clusters.

List Functions

Function	Purpose
`list_jobs`	Recent jobs with optional status and command filters (Required Cluster ID)
`get_job_log`	Full log output for a specific job (Required Cluster ID and Job id)
`create_job`	Trigger backup, restart, failover, and other cluster operations (Required Cluster ID and command string)
`kill_job`	Terminate stuck jobs (Required Cluster ID)

Example Prompt

Here are some examples of using clustercontrol-mcp for Jobs and Operations:

List recent jobs on cluster cluster_id or cluster_name

Show log for job job_id on cluster cluster_id or cluster_name

Backups and Scheduling

Manage backup jobs, review backup history, create schedules, and restore from existing backups.

List Functions

Function	Purpose
`list_backups`	Recent backups with status and method filters (Required Cluster ID)
`get_latest_backup`	Most recent backup, optionally only successful ones (Required Cluster ID)
`list_backup_schedules`	View all configured backup schedules (Required Cluster ID)
`get_backup_schedule_summary`	Summary of backup schedules for a cluster (Required Cluster ID)
`create_backup_schedule`	Create a new recurring backup schedule (Required Cluster ID)
`update_backup_schedule`	Update an existing backup schedule (Required Cluster ID)
`delete_backup_schedule`	Delete a backup schedule (Required Cluster ID)
`delete_backup`	Delete a backup record (Required Cluster ID)
`restore_backup`	Restore from an existing backup (Required Cluster ID)

Example Prompt

Here are some examples of using clustercontrol-mcp for Backups and Scheduling:

When was the last successful backup on cluster cluster_id or cluster_name?

Create a MariaDB backup schedule on cluster cluster_id or cluster_name every day at 4:25 AM using the mariabackup(full) backup method.

Tips

To successfully create a backup schedule, please mention the exact backup method name that you want to use, for example mariabackup(full) for a full backup. If you only mention use mariabackup method, the backup schedule job will be created but it will fail because the backup method is not recognized by ClusterControl.

ProxySQL

Inspect and manage ProxySQL instances including backend servers, query routing rules, and traffic statistics.

List Functions

Function	Purpose
`list_proxysql_top_queries`	Top queries by execution time through the proxy (Required Cluster ID)
`list_proxysql_rules`	Query routing rules (Required Cluster ID)
`list_proxysql_servers`	Backend server health and hostgroup configuration (Required Cluster ID)

Example Prompt

Here are some examples of using clustercontrol-mcp for ProxySQL :

List ProxySQL backend servers on cluster cluster_id or cluster_name

List ProxySQL query routing rules on cluster cluster_id or cluster_name

Show top queries through ProxySQL on cluster cluster_id or cluster_name

Configuration

View and modify configuration parameters at the cluster, node, and controller level.

List Functions

Function	Purpose
`get_cluster_config`	View cluster-level database settings (Required Cluster ID)
`get_node_config`	View node-level database settings (Required Cluster ID and Node)
`set_node_config`	Modify a node configuration parameter (with dry-run safety) (Required Cluster ID and Node)
`unset_node_config`	Reset a node configuration parameter to default (with dry-run safety) (Required Cluster ID and Node)
`get_controller_config`	View CMON controller runtime parameters (Required Cluster ID)
`set_controller_config`	Modify CMON controller runtime parameters (with dry-run safety) (Required Cluster ID)

Example Prompt

Here are some examples of using clustercontrol-mcp for Configuration :

Get configuration for node [node] on cluster cluster_id or cluster_name

Set max_connections to 150 on node [node] in cluster cluster_id or cluster_name

Reset max_connections to default on node [node] in cluster cluster_id or cluster_name

Maintenance, Audit, and Other Tools

Schedule maintenance windows, review audit logs, generate error reports, and perform other administrative tasks.

List Functions

Function	Purpose
`list_maintenance`	List maintenance windows for a cluster (Required Cluster ID)
`list_all_maintenance`	List maintenance windows across all clusters (Required Cluster ID)
`add_maintenance_window`	Schedule a maintenance window for a host (Required Cluster ID)
`remove_maintenance_window`	Remove a maintenance window by UUID (Required Cluster ID)
`remove_maintenance_windows_by_filter`	Bulk remove maintenance windows by cluster or hostname (Required Cluster ID)
`list_audit_log`	Who did what, when, and from where (Required Cluster ID)
`acknowledge_alarm`	Acknowledge a single alarm (Required Cluster ID)
`acknowledge_alarms_by_filter`	Bulk acknowledge alarms by cluster or filter (Required Cluster ID)
`list_schemas`	List all database schemas on a cluster (Required Cluster ID)
`create_schema`	Create a new database schema (Required Cluster ID)
`list_publications`	PostgreSQL logical replication publications (Required Cluster ID)
`list_subscriptions`	PostgreSQL logical replication subscriptions (Required Cluster ID)
`list_error_reports`	List generated error reports for a cluster (Required Cluster ID)
`generate_error_report`	Generate a new error report (Required Cluster ID)
`download_error_report`	Download a generated error report archive (Required Cluster ID)
`unpack_error_report`	Extract a downloaded error report archive (Required Cluster ID)

Example Prompt

Here are some examples of using clustercontrol-mcp for Maintenance, Audit, and Other Tools :

Show audit logs across all clusters

List error reports for cluster cluster_id or cluster_name

Generate an error report for cluster cluster_id or cluster_name

Tips

The download_error_report tool will download the error report to the host where clustercontrol-mcp is installed. When using the AI Assistant, you are not restricted to English, feel free to use your local language. You can also create your own custom prompts tailored to your specific needs, and integrate ClusterControl MCP with any automation tools you already have.

Attention

Please use ClusterControl MCP with AI Assistants wisely and be cautious about the information you share with them. Avoid sharing sensitive or confidential data such as API keys, or any personal information. ClusterControl MCP is designed to simplify the management of clusters maintained by ClusterControl, with a scope limited to ClusterControl-related operations only.