DEV Community: call518

MCP-Server for Ambari Cluster : MCP-Ambari-API

call518 — Mon, 22 Sep 2025 13:07:46 +0000

https://github.com/call518/MCP-Ambari-API

MCP Ambari API - Apache Hadoop Cluster Management Automation

🚀 Automate Apache Ambari operations with AI/LLM: Natural language commands for Hadoop cluster management, service control, configuration monitoring, and real-time status tracking via Model Context Protocol (MCP) tools.

Architecture & Internal (DeepWiki)

https://deepwiki.com/call518/MCP-Ambari-API

📋 Overview

MCP Ambari API is a powerful Model Context Protocol (MCP) server that enables seamless Apache Ambari cluster management through natural language commands. Built for DevOps engineers, data engineers, and system administrators who work with Hadoop ecosystems.

🎯 What You Can Do

Automated Service Management: Start, stop, restart Hadoop services (HDFS, YARN, Spark, etc.) with simple commands
Real-time Monitoring: Monitor cluster health, service status, and performance metrics
Configuration Management: View, update, and manage cluster configurations across all services
Alert Management: Track and manage cluster alerts and notifications
User & Host Management: Manage cluster users, permissions, and host assignments
Request Tracking: Monitor long-running operations with detailed progress tracking

Docuement for Airflow REST-API

Ambari API Documents

Topics

apache-ambari hadoop-cluster mcp-server cluster-automation devops-tools big-data infrastructure-management ai-automation llm-tools python-mcp

Example Queries - Cluster Info/Status

Go to More Example Queries

🚀 QuickStart Guide /w Docker

Note: The following instructions assume you are using the streamable-http mode for MCP Server.

Flow Diagram of Quickstart/Tutorial

1. Prepare Ambari Cluster (Test Target)

To set up a Ambari Demo cluster, follow the guide at: Install Ambari 3.0 with Docker

2. Run Docker-Compose

Start the MCP-Server, MCPO(MCP-Proxy for OpenAPI), and OpenWebUI.

Ensure Docker and Docker Compose are installed on your system.
Clone this repository and navigate to its root directory.
Set up environment configuration:

   # Copy environment template and configure your settings
   cp .env.example .env
   # Edit .env with your Ambari cluster information

Configure your Ambari connection in .env file:

   # Ambari cluster connection
   AMBARI_HOST=host.docker.internal
   AMBARI_PORT=7070
   AMBARI_USER=admin
   AMBARI_PASS=admin
   AMBARI_CLUSTER_NAME=TEST-AMBARI

   # (Optional) Enable authentication for streamable-http mode
   # Recommended for production environments
   REMOTE_AUTH_ENABLE=false
   REMOTE_SECRET_KEY=your-secure-secret-key-here

Run:

   docker-compose up -d

OpenWebUI will be available at: http://localhost:${DOCKER_EXTERNAL_PORT_OPENWEBUI} (default: 3001)
The MCPO-Proxy will be accessible at: http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY} (default: 8001)
The MCPO API Docs: http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY}/ambari-api/docs

3. Registering the Tool in OpenWebUI

logging in to OpenWebUI with an admin account
go to "Settings" → "Tools" from the top menu.
Enter the ambari-api Tool address (e.g., http://localhost:8000/ambari-api) to connect MCP Tools with your Ambari cluster.

4. More Examples: Using MCP Tools to Query Ambari Cluster

Below is an example screenshot showing how to query the Ambari cluster using MCP Tools in OpenWebUI:

Example Query - Cluster Configuration Review & Recommendations

Example Query - Restart HDFS Service

💡 Tool Example Queries

🔍 Cluster & Service Management

get_cluster_info

"Show cluster summary and basic information."
"What's the cluster name and version?"
"Display cluster overview with service counts."
📋 Features: Cluster name, version, service counts, basic cluster information

get_cluster_services

"Show all cluster services and their current status."
"List all services with their states."
"Display service overview for the cluster."
"Which services are running in the cluster?"
📋 Features: Service names, states, health status overview

get_service_status

"What's the status of HDFS service?"
"Check if YARN is running properly."
"Show current state of HBase service."
"Is the MapReduce service healthy?"
📋 Features: Individual service state, health check, status details

get_service_components

"Show HDFS components and which hosts they're running on."
"List all YARN components with their host assignments."
"Display component distribution for Kafka service."
"Which hosts are running NameNode components?"
📋 Features: Component-to-host mapping, service distribution analysis

get_service_details

"Get detailed information about HDFS service including all components."
"Show comprehensive YARN service overview with component states."
"Display full service details for Spark with host assignments."
📋 Features: Complete service overview with components and host details

⚙️ Service Operations

start_service / stop_service / restart_service

"Start the HDFS service."
"Stop the MapReduce service."
"Restart the YARN service."
"Please restart the HBase service."
📋 Features: Individual service lifecycle management
⚠️ Note: Returns request ID for operation tracking

start_all_services / stop_all_services / restart_all_services

"Start all cluster services."
"Stop all services in the cluster."
"Restart all cluster services."
📋 Features: Bulk service operations for entire cluster
⚠️ Warning: These are high-impact operations affecting the entire cluster

📊 Operations & Monitoring

get_active_requests

"Show all running operations."
"List current service requests in progress."
"What operations are currently active?"
"Display ongoing cluster operations."
📋 Features: Real-time operation status, request monitoring

get_request_status

"Check the status of request ID 123."
"Show progress for operation 456."
"Get details for the last restart request."
"Monitor request 789 completion status."
📋 Features: Detailed request progress, completion status, error tracking

🖥️ Host Management

list_hosts

"List all hosts in the cluster."
"Show cluster node inventory."
"Display all available hosts."
📋 Features: Host inventory, cluster node overview

get_host_details

"Show detailed information for host node1.example.com."
"Get component status on host node2.example.com."
"Display all host details with component states."
"Show hardware and component information for specific host."
📋 Features: Hardware specs, component states, host health status
💡 Tip: Omit hostname parameter to get details for all hosts

🔧 Configuration Management

dump_configurations

"Show all configuration types available."
"Display HDFS configuration settings."
"Get YARN resource manager configuration."
"Show core-site.xml configuration values."
"Find all configurations containing 'memory' settings."
"Display summarized view of all service configurations."
📋 Features: Configuration type exploration, property search, service-specific configs
💡 Usage: Use summarize=True for overview, filter parameter for specific properties

👥 User Management

list_users

"Show all cluster users."
"List users with access to Ambari."
"Display user accounts and their roles."
📋 Features: User accounts, role assignments, access permissions

get_user

"Get detailed information for user 'admin'."
"Show profile and permissions for user 'operator'."
"Display authentication details for specific user."
📋 Features: User profile, permissions, authentication source, role details

🚨 Alert Management

get_alerts_history (current mode)

"Show current active alerts."
"Display all current alert states."
"List active alerts for HDFS service."
"Show critical alerts that are currently active."
📋 Features: Real-time alert monitoring, service-specific alerts, severity filtering

get_alerts_history (history mode)

"Show alert history for the last 24 hours."
"Display HDFS alerts from yesterday."
"Get critical alerts from last week."
"Show all alerts that occurred in the past month."
"Find alerts for specific host from last 7 days."
📋 Features: Historical alert analysis, time-based filtering, trend analysis
💡 Smart Time Processing: Supports natural language time expressions in any language

📚 System Information

get_prompt_template

"Show available prompt template sections."
"Get tool usage guidelines."
"Display example queries for reference."
📋 Features: Template documentation, usage guidelines, section navigation

🐛 Usage & Configuration

This MCP server supports two connection modes: stdio (traditional) and streamable-http (Docker-based). You can configure the transport mode using CLI arguments or environment variables.

Configuration Priority: CLI arguments > Environment variables > Default values

CLI Arguments

--type (-t): Transport type (stdio or streamable-http) - Default: stdio
--host: Host address for HTTP transport - Default: 127.0.0.1
--port (-p): Port number for HTTP transport - Default: 8000
--auth-enable: Enable Bearer token authentication for streamable-http mode - Default: false
--secret-key: Secret key for Bearer token authentication (required when auth enabled)

Environment Variables

Variable	Description	Default	Project Default
`PYTHONPATH`	Python module search path for MCP server imports	-	`/app/src`
`MCP_LOG_LEVEL`	Server logging verbosity (DEBUG, INFO, WARNING, ERROR)	`INFO`	`INFO`
`FASTMCP_TYPE`	MCP transport protocol (stdio for CLI, streamable-http for web)	`stdio`	`streamable-http`
`FASTMCP_HOST`	HTTP server bind address (0.0.0.0 for all interfaces)	`127.0.0.1`	`0.0.0.0`
`FASTMCP_PORT`	HTTP server port for MCP communication	`8000`	`8000`
`REMOTE_AUTH_ENABLE`	Enable Bearer token authentication for streamable-http mode Default: false (if undefined, empty, or null)	`false`	`false`
`REMOTE_SECRET_KEY`	Secret key for Bearer token authentication Required when REMOTE_AUTH_ENABLE=true	-	`your-secret-key-here`
`AMBARI_HOST`	Ambari server hostname or IP address	`127.0.0.1`	`host.docker.internal`
`AMBARI_PORT`	Ambari server port number	`8080`	`8080`
`AMBARI_USER`	Username for Ambari server authentication	`admin`	`admin`
`AMBARI_PASS`	Password for Ambari server authentication	`admin`	`admin`
`AMBARI_CLUSTER_NAME`	Name of the target Ambari cluster	`TEST-AMBARI`	`TEST-AMBARI`
`DOCKER_EXTERNAL_PORT_OPENWEBUI`	Host port mapping for Open WebUI container	`8080`	`3001`
`DOCKER_EXTERNAL_PORT_MCP_SERVER`	Host port mapping for MCP server container	`8080`	`18001`
`DOCKER_EXTERNAL_PORT_MCPO_PROXY`	Host port mapping for MCPO proxy container	`8000`	`8001`

Note: AMBARI_CLUSTER_NAME serves as the default target cluster for operations when no specific cluster is specified. All environment variables can be configured via the .env file.

Transport Selection Logic:

Configuration Priority: CLI arguments > Environment variables > Default values

Transport Selection Logic:

CLI Priority: --type streamable-http --host 0.0.0.0 --port 18001
Environment Priority: FASTMCP_TYPE=streamable-http FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=18001
Legacy Support: FASTMCP_PORT=18001 (automatically enables streamable-http mode)
Default: stdio mode when no configuration is provided

Environment Setup

# 1. Clone the repository
git clone https://github.com/call518/MCP-Ambari-API.git
cd MCP-Ambari-API

# 2. Set up environment configuration
cp .env.example .env

# 3. Configure your Ambari connection in .env file
AMBARI_HOST=your-ambari-host
AMBARI_PORT=your-ambari-port  
AMBARI_USER=your-username
AMBARI_PASS=your-password
AMBARI_CLUSTER_NAME=your-cluster-name

🔐 Security & Authentication

Bearer Token Authentication

For streamable-http mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.

Configuration

Enable Authentication:

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here

Or via CLI:

python -m mcp_ambari_api --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

Security Levels

stdio mode (Default): Local-only access, no authentication needed
streamable-http + REMOTE_AUTH_ENABLE=false/undefined: Remote access without authentication ⚠️ NOT RECOMMENDED for production
streamable-http + REMOTE_AUTH_ENABLE=true: Remote access with Bearer token authentication ✅ RECOMMENDED for production

🔒 Default Policy: REMOTE_AUTH_ENABLE defaults to false if undefined, empty, or null. This ensures the server starts even without explicit authentication configuration.

Client Configuration

When authentication is enabled, MCP clients must include the Bearer token in the Authorization header:

{
  "mcpServers": {
    "ambari-api": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Security Best Practices

Always enable authentication when using streamable-http mode in production
Use strong, randomly generated secret keys (32+ characters recommended)
Use HTTPS when possible (configure reverse proxy with SSL/TLS)
Restrict network access using firewalls or network policies
Rotate secret keys regularly for enhanced security
Monitor access logs for unauthorized access attempts

Error Handling

When authentication fails, the server returns:

401 Unauthorized for missing or invalid tokens
Detailed error messages in JSON format for debugging

Method 1: Local MCP (transport="stdio")

{
  "mcpServers": {
    "ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "host.docker.internal",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Method 2: Remote MCP (transport="streamable-http")

On MCP-Client Host:

{
  "mcpServers": {
    "ambari-api": {
      "type": "streamable-http",
      "url": "http://localhost:18001/mcp"
    }
  }
}

With Bearer Token Authentication (Recommended for production):

{
  "mcpServers": {
    "ambari-api": {
      "type": "streamable-http", 
      "url": "http://localhost:18001/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Example usage: Claude-Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "localhost",
        "AMBARI_PORT": "7070",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

(Option) Configure Multiple Ambari Cluster

{
  "mcpServers": {
    "Ambari-Cluster-A": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "a.foo.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin-user",
        "AMBARI_PASS": "admin-pass",
        "AMBARI_CLUSTER_NAME": "AMBARI-A",
        "MCP_LOG_LEVEL": "INFO"
      }
    },
    "Ambari-Cluster-B": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "b.bar.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin-user",
        "AMBARI_PASS": "admin-pass",
        "AMBARI_CLUSTER_NAME": "AMBARI-B",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Remote Access with Authentication (Claude Desktop):

{
  "mcpServers": {
    "ambari-api-remote": {
      "type": "streamable-http",
      "url": "http://your-server-ip:18001/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

🎯 Core Features & Capabilities

Service Operations

Hadoop Service Management: Start, stop, restart HDFS, YARN, Spark, HBase, and more
Bulk Operations: Control all cluster services simultaneously
Status Monitoring: Real-time service health and performance tracking

Configuration Management

Unified Config Tool: Single interface for all configuration types (yarn-site, hdfs-site, etc.)
Bulk Configuration: Export and manage multiple configurations with filtering
Configuration Validation: Syntax checking and validation before applying changes

Monitoring & Alerting

Real-time Alerts: Current and historical cluster alerts with filtering
Request Tracking: Monitor long-running operations with detailed progress
Host Monitoring: Hardware metrics, component states, and resource utilization

Administration

User Management: Check cluster user administration
Host Management: Node registration, component assignments, and health monitoring

Available MCP Tools

This MCP server provides the following tools for Ambari cluster management:

Cluster Management

get_cluster_info - Retrieve basic cluster information and status
get_active_requests - List currently active/running operations
get_request_status - Check status and progress of specific requests

Service Management

get_cluster_services - List all services with their status
get_service_status - Get detailed status of a specific service
get_service_components - List components and host assignments for a service
get_service_details - Get comprehensive service information
start_service - Start a specific service
stop_service - Stop a specific service
restart_service - Restart a specific service
start_all_services - Start all services in the cluster
stop_all_services - Stop all services in the cluster
restart_all_services - Restart all services in the cluster

Configuration Tools

dump_configurations - Unified configuration tool (replaces get_configurations, list_configurations, and the former internal dump_all_configurations). Supports:
- Single type: dump_configurations(config_type="yarn-site")
- Bulk summary: dump_configurations(summarize=True)
- Filter by substring (type or key): dump_configurations(filter="memory")
- Service filter (narrow types by substring): dump_configurations(service_filter="yarn", summarize=True)
- Keys only (no values): dump_configurations(include_values=False)
- Limit number of types: dump_configurations(limit=10, summarize=True)

Breaking Change: get_configurations and list_configurations were removed in favor of this single, more capable tool.

Host Management

list_hosts - List all hosts in the cluster
get_host_details - Get detailed information for specific or all hosts (includes component states, hardware metrics, and service assignments)

User Management

list_users - List all users in the Ambari system with their usernames and API links
get_user - Get detailed information about a specific user including:
- Basic profile (ID, username, display name, user type)
- Status information (admin privileges, active status, login failures)
- Authentication details (LDAP user status, authentication sources)
- Group memberships, privileges, and widget layouts

Alert Management

get_alerts_history - Unified alert tool for both current and historical alerts:
- Current mode (mode="current"): Retrieve current/active alerts with real-time status
- Current alert states across cluster, services, or hosts
- Maintenance mode filtering (ON/OFF)
- Summary formats: basic summary and grouped by definition
- Detailed alert information including timestamps and descriptions
- History mode (mode="history"): Retrieve historical alert events from the cluster
- Scope filtering: cluster-wide, service-specific, or host-specific alerts
- Time range filtering: from/to timestamp support
- Pagination support for large datasets
- Common features (both modes):
- State filtering: CRITICAL, WARNING, OK, UNKNOWN alerts
- Definition filtering: filter by specific alert definition names
- Multiple output formats: detailed, summary, compact
- Unified API for consistent alert querying experience

🤝 Contributing & Support

How to Contribute

🐛 Report Bugs: GitHub Issues
💡 Request Features: Feature Requests
🔧 Submit PRs: Contributing Guidelines
📖 Improve Docs: Help make documentation better

Technologies Used

Language: Python 3.11
Framework: Model Context Protocol (MCP)
API: Apache Ambari REST API
Transport: stdio (local) and streamable-http (remote)
Deployment: Docker, Docker Compose, PyPI

Dev Env.

WSL2(networkingMode = bridged) + Docker-Desktop
- .wslconfig: tested with networkingMode = bridged
Python 3.11 venv

  ### Option-1: with uv
  uv venv --python 3.11 --seed

  ### Option-2: with pip
  python3.11 -m venv .venv
  source .venv/bin/activate
  pip install -U pip

❓ Frequently Asked Questions

Q: What Ambari versions are supported?

A: Ambari 2.7+ is recommended. Earlier versions may work but are not officially tested.

Q: Can I use this with cloud-managed Hadoop clusters?

A: Yes, as long as Ambari API endpoints are accessible, it works with on-premise, cloud, and hybrid deployments.

Q: How do I troubleshoot connection issues?

A: Check your AMBARI_HOST, AMBARI_PORT, and network connectivity. Enable debug logging with MCP_LOG_LEVEL=DEBUG.

Q: How does this compare to Ambari Web UI?

A: This provides programmatic access via AI/LLM commands, perfect for automation, scripting, and integration with modern DevOps workflows.

Contributing

🤝 Got ideas? Found bugs? Want to add cool features?

We're always excited to welcome new contributors! Whether you're fixing a typo, adding a new monitoring tool, or improving documentation - every contribution makes this project better.

Ways to contribute:

🐛 Report issues or bugs
💡 Suggest new PostgreSQL monitoring features
📝 Improve documentation
🚀 Submit pull requests
⭐ Star the repo if you find it useful!

Pro tip: The codebase is designed to be super friendly for adding new tools. Check out the existing @mcp.tool() functions in mcp_main.py.

📄 License

This project is licensed under the MIT License.

MCP-OpenStack-Ops : MCP-Server for OpenStack Cluster

call518 — Mon, 22 Sep 2025 13:01:05 +0000

GitHub: https://github.com/call518/MCP-OpenStack-Ops

MCP-OpenStack-Ops

Architecture & Internal (DeepWiki)

https://deepwiki.com/call518/MCP-OpenStack-Ops

Features

✅ Single Project Scope: Operates within the configured OS_PROJECT_NAME project scope for complete tenant isolation. All operations are restricted to resources within the specified project, ensuring data privacy and security in multi-tenant environments.
✅ OpenStack SDK Integration: Direct integration with OpenStack SDK for real-time project operations.
✅ Enhanced Operation Safety: Built-in safety controls with ALLOW_MODIFY_OPERATIONS environment variable and comprehensive error handling that prevents false success claims and provides clear guidance for asynchronous operations.
✅ Smart Async Operation Handling: Intelligent detection and guidance for OpenStack asynchronous operations (instance management, volume operations, network changes) with tool-specific timing expectations and verification commands.
✅ Enhanced Project Monitoring: Comprehensive project status reports with health scoring system, resource utilization analysis, instance state tracking, and detailed health breakdown by service categories.
✅ Complete Service Coverage: 93+ comprehensive tools covering Identity, Compute, Network, Storage, Image, Orchestration, Load Balancer, and Monitoring services within project scope.
✅ Advanced Instance Management: Enhanced server lifecycle operations with backup, migration, rescue, and administrative functions including state analysis.
✅ 🆕 Bulk Operations & Filter-based Targeting: Advanced bulk operations for instances, volumes, images, networks, keypairs, and snapshots with intelligent filtering (name_contains, status, etc.) enabling one-step operations like "stop all instances containing 'test'".
✅ 🆕 Post-Action Status Verification: Automatic status verification after operations with emoji indicators (🟢🔴🟡) providing immediate feedback on operation success and current resource states.
✅ 🆕 Unified Resource Queries: Consolidated get_instance tool replacing multiple separate query tools, providing comprehensive resource information in a single call.
✅ Server Event Tracking: Detailed server event history and lifecycle monitoring with comprehensive logging.
✅ Network Analysis: Comprehensive network operations with external/private network classification, floating IP management, and port operations within project scope.
✅ Volume Management: Comprehensive volume attachment/detachment operations with state analysis and capacity tracking.
✅ Smart Image Filtering: Access to public, community, shared, and project-owned images with intelligent visibility filtering that prevents zero-image count issues.
✅ Enterprise Features: User management, role assignments, keypair management, floating IP operations, volume snapshots within project boundaries.
✅ Intelligent Search: Flexible instance search with partial matching and case-sensitive options.
✅ Load Balancer Integration: Complete load balancer management with health monitoring within project scope.
✅ Connection Optimization: Global connection caching and automatic retry mechanisms.
✅ Multi-Project Support: Deploy multiple MCP servers with different OS_PROJECT_NAME values for complete multi-tenant project management with full isolation.
✅ Docker Support: Containerized deployment optimized for OpenStack Epoxy environments.
✅ Flexible Transport: Support for both stdio and streamable-http transports with comprehensive logging.

⚠️ Compatibility Notice: This MCP server is developed and optimized for OpenStack Epoxy (2025.1) as the primary target environment. However, it is compatible with most modern OpenStack releases (Dalmatian, Caracal, Bobcat, etc.) as the majority of APIs remain consistent across versions. Only a few specific API endpoints may require adaptation for full compatibility with older releases.

🚧 Coming Soon: Dynamic multi-version OpenStack API compatibility is actively under development and will be available in upcoming releases, providing seamless support for all major OpenStack deployments automatically.

Screenshots

OpenStack Dashboard (Epoxy 2025.1)

MCP Query Example - Cluster Status

🆕 Latest Enhancements (v1.x)

Bulk Operations & Filter-based Targeting

Revolutionary approach to resource management enabling one-step operations:

# Traditional approach (multiple steps):
1. search_instances("test") → get list
2. set_instance("vm1", "stop") → stop individually  
3. set_instance("vm2", "stop") → stop individually

# NEW enhanced approach (single step):
set_instance(action="stop", name_contains="test")  # ✨ Stops ALL instances containing "test"

Supported Tools with Enhanced Capabilities:

set_instance: Bulk lifecycle management with filtering (name_contains, status, flavor_contains, image_contains)
set_volume: Bulk volume operations with filtering (name_contains, status, size filtering)
set_image: Bulk image management with filtering (name_contains, status)
set_networks: Bulk network operations with filtering (name_contains, status)
set_keypair: Bulk keypair management with filtering (name_contains)
set_snapshot: Bulk snapshot operations with filtering (name_contains, status)

Input Format Flexibility:

# Single resource
resource_names="vm1"

# Multiple resources (comma-separated)
resource_names="vm1,vm2,vm3"

# JSON array format
resource_names='["vm1", "vm2", "vm3"]'

# Filter-based (automatic target identification)
name_contains="test", status="ACTIVE"

Post-Action Status Verification

Every operation now provides immediate feedback with visual indicators:

✅ Bulk Instance Management - Action: stop
📊 Total instances: 3
✅ Successes: 2
❌ Failures: 1

Post-Action Status:
🟢 test-vm-1: SHUTOFF  
🟢 test-vm-2: SHUTOFF
🔴 test-vm-3: ERROR

Unified Resource Queries

New consolidated get_instance tool replaces multiple separate tools:

❌ Old: get_instance_details, get_instance_info, get_instance_status, get_instance_network_info
✅ New: get_instance(instance_names="vm1,vm2") - Single tool, comprehensive information

📊 OpenStack CLI vs MCP Tools Mapping

Detailed Mapping by Category

1. 🖥️ Compute (Nova)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack server list`	`get_instance`	✅	NEW UNIFIED - Pagination, filtering support
`openstack server show`	`get_instance`	✅	ENHANCED - Replaces get_instance_by_name, get_instance_by_id
`openstack server create`	`set_instance` (action="create")	✅	ENHANCED - Bulk creation support
`openstack server start/stop/reboot`	`set_instance`	✅	ENHANCED - Bulk operations with filtering
`openstack server delete`	`set_instance` (action="delete")	✅	ENHANCED - Bulk deletion with name_contains filtering
`openstack server backup create`	`set_server_backup`	✅	Backup creation with rotation
`openstack server image create`	`set_instance` (action="snapshot")	✅	Image/snapshot creation
`openstack server shelve/unshelve`	`set_instance`	✅	Instance shelving
`openstack server lock/unlock`	`set_instance`	✅	Instance locking
`openstack server pause/unpause`	`set_instance`	✅	Instance pausing
`openstack server suspend/resume`	`set_instance`	✅	Instance suspension
`openstack server resize`	`set_instance` (action="resize")	✅	Instance resizing
`openstack server resize confirm`	`set_instance` (action="confirm_resize")	✅	Resize confirmation
`openstack server resize revert`	`set_instance` (action="revert_resize")	✅	Resize revert
`openstack server rebuild`	`set_instance` (action="rebuild")	✅	Instance rebuilding
`openstack server rescue/unrescue`	`set_instance`	✅	Recovery mode
`openstack server migrate`	`set_server_migration` (action="migrate")	✅	Live migration
`openstack server evacuate`	`set_server_migration` (action="evacuate")	✅	Server evacuation
`openstack server migration list`	`set_server_migration` (action="list")	✅	Migration listing
`openstack server migration show`	`set_server_migration` (action="show")	✅	Migration details
`openstack server migration abort`	`set_server_migration` (action="abort")	✅	Migration abort
`openstack server migration confirm`	`set_server_migration` (action="confirm")	✅	Migration confirmation
`openstack server migration force complete`	`set_server_migration` (action="force_complete")	✅	Force migration completion
`openstack server add network`	`set_server_network` (action="add_network")	✅	Network attachment
`openstack server remove network`	`set_server_network` (action="remove_network")	✅	Network detachment
`openstack server add port`	`set_server_network` (action="add_port")	✅	Port attachment
`openstack server remove port`	`set_server_network` (action="remove_port")	✅	Port detachment
`openstack server add floating ip`	`set_server_floating_ip` (action="add")	✅	Floating IP association
`openstack server remove floating ip`	`set_server_floating_ip` (action="remove")	✅	Floating IP disassociation
`openstack server add fixed ip`	`set_server_fixed_ip` (action="add")	✅	Fixed IP addition
`openstack server remove fixed ip`	`set_server_fixed_ip` (action="remove")	✅	Fixed IP removal
`openstack server add security group`	`set_server_security_group` (action="add")	✅	Security group addition
`openstack server remove security group`	`set_server_security_group` (action="remove")	✅	Security group removal
`openstack server add volume`	`set_server_volume` (action="attach")	✅	Volume attachment
`openstack server remove volume`	`set_server_volume` (action="detach")	✅	Volume detachment
`openstack server set`	`set_server_properties` (action="set")	✅	Server property setting
`openstack server unset`	`set_server_properties` (action="unset")	✅	Server property unsetting
`openstack server dump create`	`set_server_dump`	✅	Server dump creation
`openstack server event list`	`get_server_events`	✅	Server event tracking
`openstack server group list`	`get_server_groups`	✅	Server group listing
`openstack server group create/delete`	`set_server_group`	✅	Server group management
`openstack flavor list`	`get_flavor_list` (via cluster_status)	✅	Flavor listing
`openstack flavor create/delete`	`set_flavor`	✅	Flavor management
`openstack keypair list`	`get_keypair_list`	✅	Keypair listing
`openstack keypair create/delete`	`set_keypair`	✅	Keypair management
`openstack hypervisor list`	`get_hypervisor_details`	✅	Hypervisor querying
`openstack availability zone list`	`get_availability_zones`	✅	Availability zone listing

2. 🌐 Network (Neutron)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack network list`	`get_network_details`	✅	Detailed network information
`openstack network show`	`get_network_details` (name param)	✅	Specific network query
`openstack network create`	`set_networks` (action="create")	✅	ENHANCED - Bulk network creation
`openstack network delete`	`set_networks` (action="delete")	✅	ENHANCED - Bulk deletion with filtering
`openstack network set`	`set_networks` (action="update")	✅	ENHANCED - Bulk updates
`openstack subnet list`	`get_network_details` (includes subnets)	✅	Subnet information included
`openstack subnet create/delete`	`set_subnets`	✅	Subnet management
`openstack router list`	`get_routers`	✅	Router listing
`openstack router create/delete`	(Not yet implemented)	🚧	Router management
`openstack floating ip list`	`get_floating_ips`	✅	Floating IP listing
`openstack floating ip create`	`set_floating_ip` (action="create")	✅	Floating IP creation
`openstack floating ip delete`	`set_floating_ip` (action="delete")	✅	Floating IP deletion
`openstack floating ip set`	`set_floating_ip` (action="set")	✅	Floating IP property setting
`openstack floating ip show`	`set_floating_ip` (action="show")	✅	Floating IP details
`openstack floating ip unset`	`set_floating_ip` (action="unset")	✅	Floating IP property clearing
`openstack floating ip pool list`	`get_floating_ip_pools`	✅	Floating IP pool listing
`openstack floating ip port forwarding create`	`set_floating_ip_port_forwarding` (action="create")	✅	Port forwarding creation
`openstack floating ip port forwarding delete`	`set_floating_ip_port_forwarding` (action="delete")	✅	Port forwarding deletion
`openstack floating ip port forwarding list`	`set_floating_ip_port_forwarding` (action="list")	✅	Port forwarding listing
`openstack floating ip port forwarding set`	`set_floating_ip_port_forwarding` (action="set")	✅	Port forwarding updates
`openstack floating ip port forwarding show`	`set_floating_ip_port_forwarding` (action="show")	✅	Port forwarding details
`openstack security group list`	`get_security_groups`	✅	Security group listing
`openstack security group create/delete`	(Not yet implemented)	🚧	Security group management
`openstack port list`	`get_network_details` (includes ports)	✅	Port information included
`openstack port create/delete`	`set_network_ports`	✅	Port management
`openstack network qos policy list`	(Not yet implemented)	🚧	QoS policy listing
`openstack network qos policy create`	`set_network_qos_policies`	✅	QoS policy management
`openstack network agent list`	`get_service_status` (includes agents)	✅	Network agents
`openstack network agent set`	`set_network_agents`	✅	Network agent management

3. 💾 Storage (Cinder)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack volume list`	`get_volume_list`	✅	Volume listing
`openstack volume show`	`get_volume_list` (filtering)	✅	Specific volume query
`openstack volume create/delete`	`set_volume`	✅	Volume creation/deletion
`openstack volume set`	`set_volume` (action="modify")	✅	Volume property modification
`openstack volume type list`	`get_volume_types`	✅	Volume type listing
`openstack volume type create/delete`	(Not yet implemented)	🚧	Volume type management
`openstack volume snapshot list`	`get_volume_snapshots`	✅	Snapshot listing
`openstack volume snapshot create/delete`	`set_snapshot`	✅	Snapshot management
`openstack backup list`	(Not yet implemented)	🚧	Backup listing
`openstack backup create/delete`	`set_volume_backups`	✅	Volume backup management
`openstack volume transfer request list`	(Not yet implemented)	🚧	Volume transfer
`openstack server volume list`	`get_server_volumes`	✅	Server volume listing
`openstack server add/remove volume`	`set_server_volume`	✅	Server volume attach/detach
`openstack volume group list`	(Not yet implemented)	🚧	Volume group listing
`openstack volume group create`	`set_volume_groups`	✅	Volume group management
`openstack volume qos list`	(Not yet implemented)	🚧	QoS listing
`openstack volume qos create`	`set_volume_qos`	✅	QoS management

4. 🖼️ Image (Glance)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack image list`	`get_image_detail_list`	✅	Image listing
`openstack image show`	`get_image_detail_list` (filtering)	✅	Specific image query
`openstack image create`	`set_image` (action="create")	✅	Enhanced image creation with min_disk, min_ram, properties
`openstack image delete`	`set_image` (action="delete")	✅	Image deletion
`openstack image set`	`set_image` (action="update")	✅	Image property modification
`openstack image save`	`set_image` (action="save")	✅	Image download
`openstack image add project`	(Not yet implemented)	🚧	Project sharing
`openstack image member list`	(Not yet implemented)	🚧	Member listing
`openstack image member create`	`set_image_members`	✅	Image member management
`openstack image set --property`	`set_image_metadata`	✅	Image metadata
`openstack image set --public/private`	`set_image_visibility`	✅	Image visibility setting

5. 👥 Identity (Keystone)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack user list`	`get_user_list`	✅	User listing
`openstack user show`	`get_user_list` (filtering)	✅	Specific user query
`openstack user create/delete`	(Not yet implemented)	🚧	User management
`openstack project list`	`get_project_details`	✅	Project listing
`openstack project show`	`get_project_details` (name param)	✅	Specific project query
`openstack project create/delete`	`set_project`	✅	Project management
`openstack role list`	`get_role_assignments`	✅	Role listing
`openstack role assignment list`	`get_role_assignments`	✅	Role assignment listing
`openstack role create/delete`	`set_roles`	✅	Role management
`openstack domain list`	(Not yet implemented)	🚧	Domain listing
`openstack domain create/delete`	`set_domains`	✅	Domain management
`openstack group list`	(Not yet implemented)	🚧	Group listing
`openstack group create/delete`	`set_identity_groups`	✅	Group management
`openstack service list`	`get_service_status`	✅	Service listing
`openstack service create/delete`	`set_services`	✅	Service management
`openstack endpoint list`	`get_service_status` (includes endpoints)	✅	Endpoint information

6. 🔥 Orchestration (Heat)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack stack list`	`get_heat_stacks`	✅	Stack listing
`openstack stack show`	`get_heat_stacks` (filtering)	✅	Specific stack query
`openstack stack create`	`set_heat_stack` (action="create")	✅	Stack creation
`openstack stack delete`	`set_heat_stack` (action="delete")	✅	Stack deletion
`openstack stack update`	`set_heat_stack` (action="update")	✅	Stack update
`openstack stack suspend/resume`	`set_heat_stack`	✅	Stack suspend/resume
`openstack stack resource list`	(Not yet implemented)	🚧	Stack resource listing
`openstack stack event list`	(Not yet implemented)	🚧	Stack event listing
`openstack stack template show`	(Not yet implemented)	🚧	Template query
`openstack stack output list`	(Not yet implemented)	🚧	Stack output listing

7. ⚖️ Load Balancer (Octavia)

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack loadbalancer list`	`get_load_balancer_status`	✅	Load balancer listing with pagination
`openstack loadbalancer show`	`get_load_balancer_status`	✅	Load balancer detailed information
`openstack loadbalancer create`	`set_load_balancer` (action="create")	✅	Load balancer creation
`openstack loadbalancer delete`	`set_load_balancer` (action="delete")	✅	Load balancer deletion
`openstack loadbalancer set`	`set_load_balancer` (action="update")	✅	Load balancer property update
`openstack loadbalancer stats show`	`get_load_balancer_status`	✅	Load balancer statistics
`openstack loadbalancer status show`	`get_load_balancer_status`	✅	Load balancer status tree
`openstack loadbalancer failover`	`set_load_balancer` (action="failover")	✅	Load balancer failover
`openstack loadbalancer unset`	`set_load_balancer` (action="unset")	✅	Load balancer property unset
Listener Management
`openstack loadbalancer listener list`	`get_load_balancer_listeners`	✅	Listener listing for load balancer
`openstack loadbalancer listener create`	`set_load_balancer_listener` (action="create")	✅	Listener creation (HTTP/HTTPS/TCP/UDP)
`openstack loadbalancer listener delete`	`set_load_balancer_listener` (action="delete")	✅	Listener deletion
`openstack loadbalancer listener show`	`get_load_balancer_listeners`	✅	Listener detailed information
`openstack loadbalancer listener set`	`set_load_balancer_listener` (action="update")	✅	Listener property update
`openstack loadbalancer listener stats show`	`get_load_balancer_listeners`	✅	Listener statistics
`openstack loadbalancer listener unset`	`set_load_balancer_listener` (action="unset")	✅	Listener property unset
Pool Management
`openstack loadbalancer pool list`	`get_load_balancer_pools`	✅	Pool listing (all or by listener)
`openstack loadbalancer pool create`	`set_load_balancer_pool` (action="create")	✅	Pool creation with algorithms
`openstack loadbalancer pool delete`	`set_load_balancer_pool` (action="delete")	✅	Pool deletion
`openstack loadbalancer pool set`	`set_load_balancer_pool` (action="update")	✅	Pool property update
`openstack loadbalancer pool show`	`get_load_balancer_pools`	✅	Pool detailed information
`openstack loadbalancer pool stats show`	`get_load_balancer_pools`	✅	Pool statistics
`openstack loadbalancer pool unset`	`set_load_balancer_pool` (action="unset")	✅	Pool property unset
Member Management
`openstack loadbalancer member list`	`get_load_balancer_members`	✅	Pool member listing
`openstack loadbalancer member create`	`set_load_balancer_member` (action="create")	✅	Pool member creation
`openstack loadbalancer member delete`	`set_load_balancer_member` (action="delete")	✅	Pool member deletion
`openstack loadbalancer member set`	`set_load_balancer_member` (action="update")	✅	Pool member property update
`openstack loadbalancer member show`	`get_load_balancer_members`	✅	Pool member detailed information
`openstack loadbalancer member unset`	`set_load_balancer_member` (action="unset")	✅	Pool member property unset
Health Monitor Management
`openstack loadbalancer healthmonitor list`	`get_load_balancer_health_monitors`	✅	Health monitor listing
`openstack loadbalancer healthmonitor create`	`set_load_balancer_health_monitor` (action="create")	✅	Health monitor creation
`openstack loadbalancer healthmonitor delete`	`set_load_balancer_health_monitor` (action="delete")	✅	Health monitor deletion
`openstack loadbalancer healthmonitor set`	`set_load_balancer_health_monitor` (action="update")	✅	Health monitor update
`openstack loadbalancer healthmonitor show`	`get_load_balancer_health_monitors`	✅	Health monitor detailed information
`openstack loadbalancer healthmonitor unset`	`set_load_balancer_health_monitor` (action="unset")	✅	Health monitor property unset
L7 Policy Management
`openstack loadbalancer l7policy list`	`get_load_balancer_l7_policies`	✅	L7 policy listing
`openstack loadbalancer l7policy create`	`set_load_balancer_l7_policy` (action="create")	✅	L7 policy creation
`openstack loadbalancer l7policy delete`	`set_load_balancer_l7_policy` (action="delete")	✅	L7 policy deletion
`openstack loadbalancer l7policy set`	`set_load_balancer_l7_policy` (action="update")	✅	L7 policy update
`openstack loadbalancer l7policy show`	`get_load_balancer_l7_policies`	✅	L7 policy details
`openstack loadbalancer l7policy unset`	`set_load_balancer_l7_policy` (action="unset")	✅	L7 policy property unset
L7 Rule Management 🆕
`openstack loadbalancer l7rule list`	`get_load_balancer_l7_rules`	✅	L7 rule listing
`openstack loadbalancer l7rule create`	`set_load_balancer_l7_rule` (action="create")	✅	L7 rule creation
`openstack loadbalancer l7rule delete`	`set_load_balancer_l7_rule` (action="delete")	✅	L7 rule deletion
`openstack loadbalancer l7rule set`	`set_load_balancer_l7_rule` (action="update")	✅	L7 rule update
`openstack loadbalancer l7rule show`	`get_load_balancer_l7_rules`	✅	L7 rule details
`openstack loadbalancer l7rule unset`	`set_load_balancer_l7_rule` (action="unset")	✅	L7 rule property unset
Amphora Management 🆕
`openstack loadbalancer amphora list`	`get_load_balancer_amphorae`	✅	Amphora listing
`openstack loadbalancer amphora show`	`set_load_balancer_amphora` (action="show")	✅	Amphora details
`openstack loadbalancer amphora configure`	`set_load_balancer_amphora` (action="configure")	✅	Amphora configuration
`openstack loadbalancer amphora failover`	`set_load_balancer_amphora` (action="failover")	✅	Amphora failover
`openstack loadbalancer amphora delete`	N/A	❌	Not supported by OpenStack SDK
`openstack loadbalancer amphora stats show`	N/A	❌	Not supported by OpenStack SDK
Provider Management
`openstack loadbalancer provider list`	`get_load_balancer_providers`	✅	Provider listing
`openstack loadbalancer provider capability list`	`get_load_balancer_providers`	✅	Provider capability listing
Availability Zone Management 🆕
`openstack loadbalancer availabilityzone list`	`get_load_balancer_availability_zones`	✅	Availability zone listing
`openstack loadbalancer availabilityzone show`	`get_load_balancer_availability_zones`	✅	Availability zone details
`openstack loadbalancer availabilityzone create`	`set_load_balancer_availability_zone` (action="create")	✅	Availability zone creation
`openstack loadbalancer availabilityzone delete`	`set_load_balancer_availability_zone` (action="delete")	✅	Availability zone deletion
`openstack loadbalancer availabilityzone set`	`set_load_balancer_availability_zone` (action="update")	✅	Availability zone update
`openstack loadbalancer availabilityzone unset`	`set_load_balancer_availability_zone` (action="unset")	✅	Availability zone property unset
Flavor Management 🆕
`openstack loadbalancer flavor list`	`get_load_balancer_flavors`	✅	Flavor listing
`openstack loadbalancer flavor show`	`get_load_balancer_flavors`	✅	Flavor details
`openstack loadbalancer flavor create`	`set_load_balancer_flavor` (action="create")	✅	Flavor creation
`openstack loadbalancer flavor delete`	`set_load_balancer_flavor` (action="delete")	✅	Flavor deletion
`openstack loadbalancer flavor set`	`set_load_balancer_flavor` (action="update")	✅	Flavor update
`openstack loadbalancer flavor unset`	`set_load_balancer_flavor` (action="unset")	✅	Flavor property unset
Flavor Profile Management
`openstack loadbalancer flavorprofile list`	`get_load_balancer_flavor_profiles`	✅	Flavor profile listing
`openstack loadbalancer flavorprofile show`	`get_load_balancer_flavor_profiles`	✅	Flavor profile details
`openstack loadbalancer flavorprofile create`	`set_load_balancer_flavor_profile` (action="create")	✅	Flavor profile creation
`openstack loadbalancer flavorprofile set`	`set_load_balancer_flavor_profile` (action="update")	✅	Flavor profile update
`openstack loadbalancer flavorprofile unset`	`set_load_balancer_flavor_profile` (action="unset")	✅	Flavor profile property unset
`openstack loadbalancer flavorprofile delete`	`set_load_balancer_flavor_profile` (action="delete")	🚧	Pending implementation
Quota Management 🆕
`openstack loadbalancer quota list`	`get_load_balancer_quotas`	✅	Quota listing
`openstack loadbalancer quota show`	`get_load_balancer_quotas`	✅	Quota details
`openstack loadbalancer quota set`	`set_load_balancer_quota` (action="set")	✅	Quota setting
`openstack loadbalancer quota reset`	`set_load_balancer_quota` (action="reset")	✅	Quota reset

8. 📊 Monitoring & Logging

OpenStack CLI Command	MCP Tool	Status	Notes
Resource monitoring	`get_resource_monitoring`	✅	Resource monitoring
Service status	`get_service_status`	✅	Service status query
Cluster overview	`get_cluster_status`	✅	Cluster overview
Service logs	`set_service_logs`	✅	Service log management
System metrics	`set_metrics`	✅	Metrics management
Alarm management	`set_alarms`	✅	Alarm management
Compute agents	`set_compute_agents`	✅	Compute agent management
Usage statistics	`get_usage_statistics`	✅	Usage statistics

9. 📏 Usage & Quota

OpenStack CLI Command	MCP Tool	Status	Notes
`openstack quota show`	`get_quota`	✅	Quota query
`openstack quota set`	`set_quota`	✅	Quota setting
`openstack usage show`	`get_usage_statistics`	✅	Usage query
`openstack limits show`	`get_quota` (includes limits)	✅	Limits query
Resource utilization	`get_resource_monitoring`	✅	Resource utilization

Quick Start

1. Environment Setup

# Clone and navigate to project
cd MCP-OpenStack-Ops

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your OpenStack credentials

Environment Configuration

Configure your .env file with OpenStack credentials:

# OpenStack Authentication (required)
OS_AUTH_HOST=your-openstack-host
OS_AUTH_PORT=5000
OS_IDENTITY_API_VERSION=3
OS_USERNAME=your-username
OS_PASSWORD=your-password
OS_PROJECT_NAME=your-project
OS_PROJECT_DOMAIN_NAME=default
OS_USER_DOMAIN_NAME=default
OS_REGION_NAME=RegionOne

# OpenStack Service Ports (customizable)
OS_COMPUTE_PORT=8774
OS_NETWORK_PORT=9696
OS_VOLUME_PORT=8776
OS_IMAGE_PORT=9292
OS_PLACEMENT_PORT=8780
OS_HEAT_STACK_PORT=8004
OS_HEAT_STACK_CFN_PORT=8000

# MCP Server Configuration (optional)
MCP_LOG_LEVEL=INFO
ALLOW_MODIFY_OPERATIONS=false
FASTMCP_TYPE=stdio
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=8080

2. Run Server

# Start all services
docker-compose up -d

# Check logs
docker-compose logs mcp-server
docker-compose logs mcpo-proxy

Container Architecture:

mcp-server: OpenStack MCP server with tools
mcpo-proxy: OpenAPI (REST-API)
open-webui: Web interface for testing and interaction

Service URLs - Docker Internal:

MCP Server: localhost:8080 (HTTP transport)
MCPO Proxy: localhost:8000 (OpenStack API proxy)
Open WebUI: localhost:3000 (Web interface)

Service URLs - Docker External:

MCP Server: host.docker.internal:18005 (HTTP transport)
MCPO Proxy: host.docker.internal:8005 (OpenStack API proxy)
Open WebUI: host.docker.internal:3005 (Web interface)

For Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "openstack-ops": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-openstack-ops"],
      "env": {
        "OS_AUTH_HOST": "your-openstack-host",
        "OS_AUTH_PORT": "5000",
        "OS_PROJECT_NAME": "your-project",
        "OS_USERNAME": "your-username",
        "OS_PASSWORD": "your-password",
        "OS_USER_DOMAIN_NAME": "Default",
        "OS_PROJECT_DOMAIN_NAME": "Default",
        "OS_REGION_NAME": "RegionOne",
        "OS_IDENTITY_API_VERSION": "3",
        "OS_INTERFACE": "internal",
        "OS_COMPUTE_PORT": "8774",
        "OS_NETWORK_PORT": "9696",
        "OS_VOLUME_PORT": "8776",
        "OS_IMAGE_PORT": "9292",
        "OS_PLACEMENT_PORT": "8780",
        "OS_HEAT_STACK_PORT": "8004",
        "OS_HEAT_STACK_CFN_PORT": "18888",
        "ALLOW_MODIFY_OPERATIONS": "false",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Server Configuration

Command Line Options

uv run python -m mcp_openstack_ops --help

Options:
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Logging level
  --type {stdio,streamable-http}
                        Transport type (default: stdio)
  --host HOST          Host address for HTTP transport (default: 127.0.0.1)
  --port PORT          Port number for HTTP transport (default: 8080)
  --auth-enable        Enable Bearer token authentication for streamable-http mode
  --secret-key SECRET  Secret key for Bearer token authentication

Environment Variables

Variable	Description	Default	Usage
OpenStack Authentication
`OS_AUTH_HOST`	OpenStack Identity service host	Required	Authentication host address
`OS_AUTH_PORT`	OpenStack Identity service port	Required	Authentication port
`OS_USERNAME`	OpenStack username	Required	User credentials
`OS_PASSWORD`	OpenStack password	Required	User credentials
`OS_PROJECT_NAME`	OpenStack project name	Required	Project scope
`OS_IDENTITY_API_VERSION`	Identity API version	`3`	API version
`OS_PROJECT_DOMAIN_NAME`	Project domain name	`default`	Domain scope
`OS_USER_DOMAIN_NAME`	User domain name	`default`	Domain scope
`OS_REGION_NAME`	OpenStack region	`RegionOne`	Regional scope
OpenStack Service Ports
`OS_COMPUTE_PORT`	Compute service port	`8774`	Nova endpoint
`OS_NETWORK_PORT`	Network service port	`9696`	Neutron endpoint
`OS_VOLUME_PORT`	Volume service port	`8776`	Cinder endpoint
`OS_IMAGE_PORT`	Image service port	`9292`	Glance endpoint
`OS_PLACEMENT_PORT`	Placement service port	`8780`	Placement endpoint
`OS_HEAT_STACK_PORT`	Heat orchestration service port	`8004`	Heat API endpoint
`OS_HEAT_STACK_CFN_PORT`	Heat CloudFormation service port	`18888`	Heat CFN API endpoint
MCP Server Configuration
`MCP_LOG_LEVEL`	Logging level	`INFO`	Development debugging
`ALLOW_MODIFY_OPERATIONS`	Enable modify operations	`false`	Safety control for state modifications
`FASTMCP_TYPE`	Transport type	`stdio`	Rarely needed to change
`FASTMCP_HOST`	HTTP host address	`127.0.0.1`	For HTTP mode only
`FASTMCP_PORT`	HTTP port number	`8080`	For HTTP mode only
Authentication (Optional)
`REMOTE_AUTH_ENABLE`	Enable Bearer token authentication for streamable-http mode	`false`	Production security
`REMOTE_SECRET_KEY`	Secret key for Bearer token authentication	Required when auth enabled	Production security

🔒 Project Isolation & Security

Single Project Scope Operation

MCP-OpenStack-Ops operates within a strictly defined project scope determined by the OS_PROJECT_NAME environment variable. This provides complete tenant isolation and data privacy in multi-tenant OpenStack environments.

Key Security Features:

100% Complete Resource Isolation: All operations are restricted to resources within the specified project with enhanced security validation
Zero Cross-tenant Data Leakage: Advanced project ownership validation prevents access to resources from other projects
Multi-layer Security Filtering: Each service implements intelligent resource filtering by current project ID with additional validation
Secure Resource Lookup: All resource searches use project-scoped lookup with ownership verification
Shared Resource Access: Intelligently includes shared/public resources (networks, images) while maintaining strict security boundaries
Cross-Project Access Prevention: Enhanced protection against accidental operations on similarly-named resources in other projects

Filtered Resources by Project:

Service	Project-Scoped Resources	Notes
Identity	Users (via role assignments), Role assignments	Only users with roles in current project
Compute	Instances, Flavors (embedded data), Keypairs	All instances within project scope
Image	Private images (owned), Public/Community/Shared images	Smart filtering prevents zero-image issues
Network	Networks, Subnets, Security Groups, Floating IPs, Routers	Includes shared/external networks for access
Storage	Volumes, Snapshots, Backups	All storage resources within project
Orchestration	Heat Stacks, Stack Resources	All orchestration within project
Load Balancer	Load Balancers, Listeners, Pools	All load balancing within project
Monitoring	Resource usage, Project quotas	Project-specific monitoring data

Security Validation & Testing

Project Isolation Security Test

To verify that project isolation is working correctly, run the included security test:

# Run project isolation security test
python test_project_isolation.py

Expected Test Results:

🔒 OpenStack Project Isolation Security Test
==================================================
📋 Testing project isolation for: your-project

1️⃣ Testing Connection and Project ID...
✅ Connection successful
✅ Current project ID: abc123-def456-ghi789
✅ Project name 'your-project' matches project ID

2️⃣ Testing Resource Ownership Validation...
✅ Found 5 compute instances
   Instance web-server-01: ✅ Owned
   Instance db-server-01: ✅ Owned
✅ Found 3/8 owned networks
✅ Found 10/10 owned volumes

3️⃣ Testing Service-Level Project Filtering...
✅ Compute service returned 5 instances
✅ Network service returned 3 networks  
✅ Storage service returned 10 volumes

4️⃣ Testing Secure Resource Lookup...
ℹ️  Network 'admin' not found or not accessible in current project
ℹ️  Instance 'demo' not found or not accessible in current project

🎯 Project Isolation Test Results
========================================
✅ All security tests passed!
✅ Project 'your-project' isolation verified
✅ Cross-project access prevention confirmed

🔒 Your OpenStack MCP Server is properly secured!

Security Features Validated:

✅ Project ID verification and matching
✅ Resource ownership validation for all services
✅ Service-level project filtering
✅ Secure resource lookup with cross-project protection
✅ Prevention of accidental operations on other projects' resources

For managing multiple OpenStack projects, deploy multiple MCP server instances with different OS_PROJECT_NAME values:

Example: Managing 3 Projects

# Project 1: Production Environment
OS_PROJECT_NAME=production
# ... other config
python -m mcp_openstack_ops --type stdio

# Project 2: Development Environment  
OS_PROJECT_NAME=development
# ... other config  
python -m mcp_openstack_ops --type streamable-http --port 8001

# Project 3: Testing Environment
OS_PROJECT_NAME=testing  
# ... other config
python -m mcp_openstack_ops --type streamable-http --port 8002

Claude Desktop Multi-Project Configuration Example:

{
  "mcpServers": {
    "openstack-production": {
      "command": "python",
      "args": ["-m", "mcp_openstack_ops", "--type", "stdio"],
      "env": {
        "OS_PROJECT_NAME": "production",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "your-password",
        "OS_AUTH_HOST": "192.168.35.2"
      }
    },
    "openstack-development": {
      "command": "python", 
      "args": ["-m", "mcp_openstack_ops", "--type", "stdio"],
      "env": {
        "OS_PROJECT_NAME": "development",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "your-password", 
        "OS_AUTH_HOST": "192.168.35.2"
      }
    },
    "openstack-testing": {
      "command": "python",
      "args": ["-m", "mcp_openstack_ops", "--type", "stdio"], 
      "env": {
        "OS_PROJECT_NAME": "testing",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "your-password",
        "OS_AUTH_HOST": "192.168.35.2"
      }
    }
  }
}

This allows Claude to access each project independently with complete isolation between environments.

📁 Ready-to-use Configuration File:

A complete multi-project configuration example is available at mcp-config.json.multi-project:

Production: Read-only operations for safety (ALLOW_MODIFY_OPERATIONS=false)
Development: Full operations enabled (ALLOW_MODIFY_OPERATIONS=true)
Testing: Debug logging enabled (MCP_LOG_LEVEL=DEBUG)

# Copy and customize the multi-project configuration
cp mcp-config.json.multi-project ~/.config/claude-desktop/mcp_servers.json
# Edit with your OpenStack credentials

Safety Controls

Modification Operations Protection

By default, all operations that can modify or delete OpenStack resources are disabled for safety:

# Default setting - Only read-only operations allowed
ALLOW_MODIFY_OPERATIONS=false

Protected Operations (when ALLOW_MODIFY_OPERATIONS=false):

Instance management (start, stop, restart, pause, unpause)
Volume operations (create, delete, attach, detach)
Keypair management (create, delete, import)
Floating IP operations (create, delete, associate, disassociate)
Snapshot management (create, delete)
Image management (create, delete, update)
Heat stack operations (create, delete, update)

Always Available (Read-Only Operations):

Cluster status and monitoring
Resource listings (instances, volumes, networks, etc.)
Service status checks
Usage and quota information
Search and filtering operations

⚠️ To Enable Modify Operations:

# Enable all operations (USE WITH CAUTION)
ALLOW_MODIFY_OPERATIONS=true

Tool Registration Behavior:

When ALLOW_MODIFY_OPERATIONS=false: Only read-only tools are registered with the MCP server
When ALLOW_MODIFY_OPERATIONS=true: All tools (read-only + modify operations) are registered
Tool availability is determined at server startup - restart required after changing this setting

Best Practices:

Keep ALLOW_MODIFY_OPERATIONS=false in production environments
Enable modify operations only in development/testing environments
Use separate configurations for different environments
Review operations before enabling modify capabilities
Restart the MCP server after changing the ALLOW_MODIFY_OPERATIONS setting

💬 Example Queries & Usage Patterns

For comprehensive examples of how to interact with this MCP server, including natural language queries and their corresponding tool mappings, see:

📖 Example Queries & Usage Patterns

This section includes:

🎯 Cluster overview and status queries
�️ Instance management operations
🌐 Network configuration tasks
� Storage management workflows
🔥 Heat orchestration examples
⚖️ Load balancer operations
� Advanced search patterns
📊 Monitoring and troubleshooting
🧠 Complex multi-tool query combinations

Performance Optimization

Large-Scale Environment Support

The MCP server is optimized for large OpenStack environments with thousands of instances:

Pagination Features:

Default limits prevent memory overflow (50 instances per request)
Configurable safety limits (maximum 200 instances per request)
Offset-based pagination for browsing large datasets
Performance metrics tracking (processing time, instances per second)

Search Optimization:

2-phase search process (basic info filtering → detailed info retrieval)
Intelligent caching with connection reuse
Selective API calls to minimize overhead
Case-sensitive search options for precise filtering

Connection Management:

Global connection caching with validity testing
Automatic retry mechanisms for transient failures
Connection pooling for high-throughput scenarios

Usage Examples:

# Safe large environment browsing
get_instance_details(limit=50, offset=0)     # First 50 instances
get_instance_details(limit=50, offset=50)    # Next 50 instances

# Emergency override for small environments
get_instance_details(include_all=True)       # All instances (use with caution)

# Optimized search for large datasets
search_instances("web", "name", limit=20)    # Search with reasonable limit

Development

Adding New Tools

Edit src/mcp_openstack_ops/mcp_main.py to add new MCP tools:

@mcp.tool()
async def my_openstack_tool(param: str) -> str:
    """
    Brief description of the tool's purpose.

    Functions:
    - List specific functions this tool performs
    - Describe the operations it enables
    - Mention when to use this tool

    Use when user requests [specific scenarios].

    Args:
        param: Description of the parameter

    Returns:
        Description of return value format.
    """
    try:
        logger.info(f"Tool called with param: {param}")
        # Implementation using functions.py helpers
        result = my_helper_function(param)

        response = {
            "timestamp": datetime.now().isoformat(),
            "result": result
        }

        return json.dumps(response, indent=2, ensure_ascii=False)

    except Exception as e:
        error_msg = f"Error: Failed to execute tool - {str(e)}"
        logger.error(error_msg)
        return error_msg

Helper Functions

Add utility functions to src/mcp_openstack_ops/functions.py:

def my_helper_function(param: str) -> dict:
    """Helper function for OpenStack operations"""
    try:
        conn = get_openstack_connection()

        # OpenStack SDK operations
        result = conn.some_service.some_operation(param)

        logger.info(f"Operation completed successfully")
        return {"success": True, "data": result}

    except Exception as e:
        logger.error(f"Helper function error: {e}")
        raise

Testing & Validation

Local Testing

# Test with MCP Inspector (recommended)
./scripts/run-mcp-inspector-local.sh

# Test with debug logging
MCP_LOG_LEVEL=DEBUG uv run python -m mcp_openstack_ops

# Validate OpenStack connection
uv run python -c "from src.mcp_openstack_ops.functions import get_openstack_connection; print(get_openstack_connection())"

🔐 Security & Authentication

Bearer Token Authentication

For streamable-http mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.

Configuration

Enable Authentication:

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here

Or via CLI:

uv run python -m mcp_openstack_ops --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

Security Levels

stdio mode (Default): Local-only access, no authentication needed
streamable-http + REMOTE_AUTH_ENABLE=false/undefined: Remote access without authentication ⚠️ NOT RECOMMENDED for production
streamable-http + REMOTE_AUTH_ENABLE=true: Remote access with Bearer token authentication ✅ RECOMMENDED for production

🔒 Default Policy: REMOTE_AUTH_ENABLE defaults to false if undefined, empty, or null. This ensures the server starts even without explicit authentication configuration.

Client Configuration

When authentication is enabled, MCP clients must include the Bearer token in the Authorization header:

{
  "mcpServers": {
    "openstack-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Security Best Practices

Always enable authentication when using streamable-http mode in production
Use strong, randomly generated secret keys (32+ characters recommended)
Use HTTPS when possible (configure reverse proxy with SSL/TLS)
Restrict network access using firewalls or network policies
Rotate secret keys regularly for enhanced security
Monitor access logs for unauthorized access attempts

Error Handling

When authentication fails, the server returns:

401 Unauthorized for missing or invalid tokens
Detailed error messages in JSON format for debugging

🎯 Recent Improvements & Enhancements

🔒 Complete Project Isolation Security Implementation ✨

100% Project Isolation Guarantee:

✅ Multi-layer Security Validation: Added comprehensive project ownership validation for all resource operations
✅ Enhanced Delete Operation Security: All delete operations now use secure project-scoped lookup with ownership verification
✅ Create Operation Security: Resource references during creation (networks, images, etc.) verified for project ownership
✅ Query Security Enhancement: All list/get operations include explicit project validation with resource ownership checks
✅ Cross-Project Access Prevention: Advanced protection against accidental operations on similarly-named resources in other projects
✅ Security Test Suite: Added test_project_isolation.py for comprehensive security validation

Technical Implementation:

✅ New Security Utilities: Added get_current_project_id(), validate_resource_ownership(), find_resource_by_name_or_id() functions
✅ Service-Level Security: Enhanced all service modules (compute, network, storage, etc.) with project ownership validation
✅ Secure Resource Lookup: Replaced unsafe name-based loops with secure project-scoped resource lookup
✅ Error Message Enhancement: Improved error messages to clearly indicate project access restrictions

Complete Project Scoping Implementation

Enhanced Security & Tenant Isolation:

✅ All Services Project-Scoped: Identity, Compute, Network, Storage, Image, Orchestration, Load Balancer, and Monitoring services now filter resources by current project ID
✅ Zero Cross-Tenant Data Leakage: Automatic filtering at OpenStack SDK level using current_project_id
✅ Smart Resource Access: Intelligent handling of shared/public resources (networks, images) while maintaining security boundaries

Fixed Image Service Issues 🖼️

Resolved Zero-Image Count Problems:

✅ Enhanced Image Filtering: Now includes public, community, shared, and project-owned images
✅ Intelligent Visibility Handling: Proper handling of different image visibility types
✅ Prevented Empty Results: Fixed filtering logic that was too restrictive

Improved vCPU/RAM Calculation ⚡

Fixed Instance Resource Display:

✅ Embedded Flavor Data Usage: Uses server.flavor attributes directly, avoiding 404 API errors
✅ Accurate Resource Reporting: Proper vCPU and RAM values in cluster status reports
✅ Eliminated API Failures: No more flavor lookup failures causing zero resource values

Enhanced Documentation 📚

Comprehensive Project Scoping Documentation:

✅ Multi-Project Management Guide: Complete setup instructions for managing multiple OpenStack projects
✅ Security & Isolation Details: Detailed explanation of tenant isolation features
✅ Ready-to-Use Configuration: Pre-configured mcp-config.json.multi-project for quick setup
✅ Updated Environment Variables: Enhanced .env.example with project scoping guidance

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

MCP-Server for PostgreSQL Operations

call518 — Fri, 22 Aug 2025 17:16:09 +0000

https://github.com/call518/MCP-PostgreSQL-Ops

MCP Server for PostgreSQL Operations and Database Monitoring

Overview

A professional MCP server for PostgreSQL database operations, monitoring, and management. Supports PostgreSQL 12-17 with comprehensive database analysis, performance monitoring, and intelligent maintenance recommendations through natural language queries. Most features work independently, but advanced query analysis capabilities are enhanced when pg_stat_statements and (optionally) pg_stat_monitor extensions are installed.

Architecture & Internal (DeepWiki)

https://deepwiki.com/call518/MCP-PostgreSQL-Ops

Features

✅ Zero Configuration: Works with PostgreSQL 12-17 out-of-the-box with automatic version detection.
✅ Natural Language: Ask questions like "Show me slow queries" or "Analyze table bloat."
✅ Production Safe: Read-only operations, RDS/Aurora compatible with regular user permissions.
✅ Extension Enhanced: Optional pg_stat_statements and pg_stat_monitor for advanced query analytics.
✅ Comprehensive Database Monitoring: Performance analysis, bloat detection, and maintenance recommendations.
✅ Smart Query Analysis: Slow query identification with pg_stat_statements and pg_stat_monitor integration.
✅ Schema & Relationship Discovery: Database structure exploration with detailed relationship mapping.
✅ VACUUM & Autovacuum Intelligence: Real-time maintenance monitoring and effectiveness analysis.
✅ Multi-Database Operations: Seamless cross-database analysis and monitoring.
✅ Enterprise-Ready: Safe read-only operations with RDS/Aurora compatibility.
✅ Developer-Friendly: Simple codebase for easy customization and tool extension.

🔧 Advanced Capabilities

Version-aware I/O statistics (enhanced on PostgreSQL 16+).
Real-time connection and lock monitoring.
Background process and checkpoint analysis.
Replication status and WAL monitoring.
Database capacity and bloat analysis.

Tool Usage Examples

📸 More Examples with Screenshots →

⭐ Quickstart (5 minutes)

Note: The postgresql container included in docker-compose.yml is intended for quickstart testing purposes only. You can connect to your own PostgreSQL instance by adjusting the environment variables as needed.

If you want to use your own PostgreSQL instance instead of the built-in test container:

Update the target PostgreSQL connection information in your .env file (see POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB).

In docker-compose.yml, comment out (disable) the postgres and postgres-init-extensions containers to avoid starting the built-in test database.

Flow Diagram of Quickstart/Tutorial

1. Environment Setup

Note: While superuser privileges provide access to all databases and system information, the MCP server also works with regular user permissions for basic monitoring tasks.

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### Check and modify .env file

bash
cp .env.example .env


### No need to modify defaults, but if using your own PostgreSQL server, edit below:

bash
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # Default connection DB. Superusers can access all DBs.


> **Note**: `PGDATA=/data/db` is preconfigured for the Percona PostgreSQL Docker image, which requires this specific path for proper write permissions.

2. Start Demo Containers

# Start all containers including built-in PostgreSQL for testing
docker-compose up -d

# Alternative: If using your own PostgreSQL instance
# Comment out postgres and postgres-init-extensions services in docker-compose.yml
# Then use the custom configuration:
# docker-compose -f docker-compose.custom-db.yml up -d

3. Access to OpenWebUI

http://localhost:3003/

The list of MCP tool features provided by swagger can be found in the MCPO API Docs URL.
- e.g: http://localhost:8003/docs

4. Registering the Tool in OpenWebUI

logging in to OpenWebUI with an admin account
go to "Settings" → "Tools" from the top menu.
Enter the postgresql-ops Tool address (e.g., http://localhost:8003/postgresql-ops) to connect MCP Tools.
Setup Ollama or OpenAI.

(NOTE) Sample Test Data Overview

The create-test-data.sql script is executed by the postgres-init-extensions container (defined in docker-compose.yml) on first startup, automatically generating comprehensive test databases for MCP tool testing:

Database	Purpose	Schema & Tables	Scale
ecommerce	E-commerce system	public: categories, products, customers, orders, order_items	10 categories, 500 products, 100 customers, 200 orders, 400 order items
analytics	Analytics & reporting	public: page_views, sales_summary	1,000 page views, 30 sales summaries
inventory	Warehouse management	public: suppliers, inventory_items, purchase_orders	10 suppliers, 100 items, 50 purchase orders
hr_system	HR management	public: departments, employees, payroll	5 departments, 50 employees, 150 payroll records

Test users created: app_readonly, app_readwrite, analytics_user, backup_user

Optimized for testing: Intentional table bloat, various indexes (used/unused), time-series data, complex relationships

Tool Compatibility Matrix

Automatic Adaptation: All tools work transparently across supported versions - no configuration needed!

🟢 Extension-Independent Tools (No Extensions Required)

Tool Name	Extensions Required	PG 12	PG 13	PG 14	PG 15	PG 16	PG 17	System Views/Tables Used
`get_server_info`	❌ None	✅	✅	✅	✅	✅	✅	`version()`, `pg_extension`
`get_active_connections`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_activity`
`get_postgresql_config`	❌ None	✅	✅	✅	✅	✅	✅	`pg_settings`
`get_database_list`	❌ None	✅	✅	✅	✅	✅	✅	`pg_database`
`get_table_list`	❌ None	✅	✅	✅	✅	✅	✅	`information_schema.tables`
`get_table_schema_info`	❌ None	✅	✅	✅	✅	✅	✅	`information_schema.*`, `pg_indexes`
`get_database_schema_info`	❌ None	✅	✅	✅	✅	✅	✅	`pg_namespace`, `pg_class`, `pg_proc`
`get_table_relationships`	❌ None	✅	✅	✅	✅	✅	✅	`information_schema.*` (constraints)
`get_user_list`	❌ None	✅	✅	✅	✅	✅	✅	`pg_user`, `pg_roles`
`get_index_usage_stats`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_indexes`
`get_database_size_info`	❌ None	✅	✅	✅	✅	✅	✅	`pg_database_size()`
`get_table_size_info`	❌ None	✅	✅	✅	✅	✅	✅	`pg_total_relation_size()`
`get_vacuum_analyze_stats`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_current_database_info`	❌ None	✅	✅	✅	✅	✅	✅	`pg_database`, `current_database()`
`get_table_bloat_analysis`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_database_bloat_overview`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_autovacuum_status`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_autovacuum_activity`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_running_vacuum_operations`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_activity`
`get_vacuum_effectiveness_analysis`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_table_bloat_analysis`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_database_bloat_overview`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_lock_monitoring`	❌ None	✅	✅	✅	✅	✅	✅	`pg_locks`, `pg_stat_activity`
`get_wal_status`	❌ None	✅	✅	✅	✅	✅	✅	`pg_current_wal_lsn()`
`get_database_stats`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_database`
`get_table_io_stats`	❌ None	✅	✅	✅	✅	✅	✅	`pg_statio_user_tables`
`get_index_io_stats`	❌ None	✅	✅	✅	✅	✅	✅	`pg_statio_user_indexes`
`get_database_conflicts_stats`	❌ None	✅	✅	✅	✅	✅	✅	`pg_stat_database_conflicts`

🚀 Version-Aware Tools (Auto-Adapting)

Tool Name	Extensions Required	PG 12	PG 13	PG 14	PG 15	PG 16	PG 17	Special Features
`get_io_stats`	❌ None	✅ Basic	✅ Basic	✅ Basic	✅ Basic	✅ Enhanced	✅ Enhanced	PG16+: `pg_stat_io` support
`get_bgwriter_stats`	❌ None	✅	✅	✅	✅ Special	✅	✅	PG15: Separate checkpointer stats
`get_replication_status`	❌ None	✅ Compatible	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	PG13+: `wal_status`, `safe_wal_size`; PG16+: enhanced WAL receiver
`get_all_tables_stats`	❌ None	✅ Compatible	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	PG13+: `n_ins_since_vacuum` tracking for vacuum maintenance optimization
`get_user_functions_stats`	⚙️ Config Required	✅	✅	✅	✅	✅	✅	Requires `track_functions=pl`

🟡 Extension-Dependent Tools (Extensions Required)

Tool Name	Required Extension	PG 12	PG 13	PG 14	PG 15	PG 16	PG 17	Notes
`get_pg_stat_statements_top_queries`	`pg_stat_statements`	✅ Compatible	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	PG12: `total_time` → `total_exec_time`; PG13+: native `total_exec_time`
`get_pg_stat_monitor_recent_queries`	`pg_stat_monitor`	✅ Compatible	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	✅ Enhanced	PG12: `total_time` → `total_exec_time`; PG13+: native `total_exec_time`

📋 PostgreSQL 18 Support: PostgreSQL 18 is currently in beta phase and not yet supported by Percona Distribution PostgreSQL. Support will be added once PostgreSQL 18 reaches stable release and distribution support becomes available.

Usage Examples

Claude Desktop Integration

(Recommended) Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

"Show all active connections in a clear and readable html table format."

"Show all relationships for customers table in ecommerce database as a Mermaid diagram."

(Optional) Run with Local Source:

{
  "mcpServers": {
    "postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.mcp_postgresql_ops.mcp_main"],
      "env": {
        "PYTHONPATH": "/path/to/MCP-PostgreSQL-Ops",
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

Run MCP-Server as Standalon

/w Pypi and uvx (Recommended)

# Stdio mode
uvx --python 3.11 mcp-postgresql-ops \
  --type stdio

# HTTP mode
uvx --python 3.11 mcp-postgresql-ops
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --log-level DEBUG

(Option) Configure Multiple PostgreSQL Instances

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "a.foo.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    },
    "Postgresql-B": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

/w Local Source

# Stdio mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
  --type stdio

# HTTP mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --log-level DEBUG

Environment Variables

Variable	Description	Default	Project Default
`PYTHONPATH`	Python module search path for MCP server imports	-	`/app/src`
`MCP_LOG_LEVEL`	Server logging verbosity (DEBUG, INFO, WARNING, ERROR)	`INFO`	`INFO`
`FASTMCP_TYPE`	MCP transport protocol (stdio for CLI, streamable-http for web)	`stdio`	`streamable-http`
`FASTMCP_HOST`	HTTP server bind address (0.0.0.0 for all interfaces)	`127.0.0.1`	`0.0.0.0`
`FASTMCP_PORT`	HTTP server port for MCP communication	`8080`	`8080`
`PGSQL_VERSION`	PostgreSQL major version for Docker image selection	`17`	`17`
`PGDATA`	PostgreSQL data directory inside Docker container (Do not modify)	`/var/lib/postgresql/data`	`/data/db`
`POSTGRES_HOST`	PostgreSQL server hostname or IP address	`127.0.0.1`	`host.docker.internal`
`POSTGRES_PORT`	PostgreSQL server port number	`5432`	`15432`
`POSTGRES_USER`	PostgreSQL connection username (needs read permissions)	`postgres`	`postgres`
`POSTGRES_PASSWORD`	PostgreSQL user password (supports special characters)	`changeme!@34`	`changeme!@34`
`POSTGRES_DB`	Default database name for connections	`testdb`	`ecommerce`
`POSTGRES_MAX_CONNECTIONS`	PostgreSQL max_connections configuration parameter	`200`	`200`
`DOCKER_EXTERNAL_PORT_OPENWEBUI`	Host port mapping for Open WebUI container	`8080`	`3003`
`DOCKER_EXTERNAL_PORT_MCP_SERVER`	Host port mapping for MCP server container	`8080`	`18003`
`DOCKER_EXTERNAL_PORT_MCPO_PROXY`	Host port mapping for MCPO proxy container	`8000`	`8003`

Note: POSTGRES_DB serves as the default target database for operations when no specific database is specified. In Docker environments, if set to a non-default name, this database will be automatically created during initial PostgreSQL startup.

Prerequisites

Required PostgreSQL Extensions

For more details, see the ## Tool Compatibility Matrix

Note: Most MCP tools work without any PostgreSQL extensions. section below. Some advanced performance analysis tools require the following extensions:

-- Query performance statistics (required only for get_pg_stat_statements_top_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Advanced monitoring (optional, used by get_pg_stat_monitor_recent_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

Quick Setup: For new PostgreSQL installations, add to postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'

Then restart PostgreSQL and run the CREATE EXTENSION commands above.

pg_stat_statements is required only for slow query analysis tools.
pg_stat_monitor is optional and used for real-time query monitoring.
All other tools work without these extensions.

Minimum Requirements

PostgreSQL 12+ (tested with PostgreSQL 17)
Python 3.11
Network access to PostgreSQL server
Read permissions on system catalogs

Required PostgreSQL Configuration

⚠️ Statistics Collection Settings:
Some MCP tools require specific PostgreSQL configuration parameters to collect statistics. Choose one of the following configuration methods:

Tools affected by these settings:

get_user_functions_stats: Requires track_functions = pl or track_functions = all
get_table_io_stats & get_index_io_stats: More accurate timing with track_io_timing = on
get_database_stats: Enhanced I/O timing with track_io_timing = on

Verification:
After applying any method, verify the settings:

SELECT name, setting, context FROM pg_settings WHERE name IN ('track_activities', 'track_counts', 'track_io_timing', 'track_functions') ORDER BY name;

       name       | setting |  context  
------------------+---------+-----------
 track_activities | on      | superuser
 track_counts     | on      | superuser
 track_functions  | pl      | superuser
 track_io_timing  | on      | superuser
(4 rows)

Method 1: postgresql.conf (Recommended for Self-Managed PostgreSQL)

Add the following to your postgresql.conf:

# Basic statistics collection (usually enabled by default)
track_activities = on
track_counts = on

# Required for function statistics tools
track_functions = pl    # Enables PL/pgSQL function statistics collection

# Optional but recommended for accurate I/O timing
track_io_timing = on    # Enables I/O timing statistics collection

Then restart PostgreSQL server.

Method 2: PostgreSQL Startup Parameters

For Docker or command-line PostgreSQL startup:

# Docker example
docker run -d \
  -e POSTGRES_PASSWORD=mypassword \
  postgres:17 \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

# Direct postgres command
postgres -D /data \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

Method 3: Dynamic Configuration (AWS RDS, Azure, GCP, Managed Services)

For managed PostgreSQL services where you cannot modify postgresql.conf, use SQL commands to change settings dynamically:

-- Enable basic statistics collection (usually enabled by default)
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- Enable function statistics collection (requires superuser privileges)
ALTER SYSTEM SET track_functions = 'pl';

-- Enable I/O timing statistics (optional but recommended)
ALTER SYSTEM SET track_io_timing = 'on';

-- Reload configuration without restart (run separately)
SELECT pg_reload_conf();

Alternative for session-level testing:

-- Set for current session only (temporary)
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

Note: When using command-line tools, run each SQL statement separately to avoid transaction block errors.

RDS/Aurora Compatibility

This server is read-only and works with regular roles on RDS/Aurora. For advanced analysis enable pg_stat_statements; pg_stat_monitor is not available on managed engines.
On RDS/Aurora, prefer DB Parameter Group over ALTER SYSTEM for persistent settings.

  -- Verify preload setting
  SHOW shared_preload_libraries;

  -- Enable extension in target DB
  CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

  -- Recommended visibility for monitoring
  GRANT pg_read_all_stats TO <app_user>;

Example Queries

🟢 Extension-Independent Tools (Always Available)

get_server_info
- "Show PostgreSQL server version and extension status."
- "Check if pg_stat_statements is installed."
get_active_connections
- "Show all active connections."
- "List current sessions with database and user."
get_postgresql_config
- "Show all PostgreSQL configuration parameters."
- "Find all memory-related configuration settings."
get_database_list
- "List all databases and their sizes."
- "Show database list with owner information."
get_table_list
- "List all tables in the ecommerce database."
- "Show table sizes in the public schema."
get_table_schema_info
- "Show detailed schema information for the customers table in ecommerce database."
- "Get column details and constraints for products table in ecommerce database."
- "Analyze table structure with indexes and foreign keys for orders table in sales schema of ecommerce database."
- "Show schema overview for all tables in public schema of inventory database."
- 📋 Features: Column types, constraints, indexes, foreign keys, table metadata
- ⚠️ Required: database_name parameter must be specified
get_database_schema_info
- "Show all schemas in ecommerce database with their contents."
- "Get detailed information about sales schema in ecommerce database."
- "Analyze schema structure and permissions for inventory database."
- "Show schema overview with table counts and sizes for hr_system database."
- 📋 Features: Schema owners, permissions, object counts, sizes, contents
- ⚠️ Required: database_name parameter must be specified
get_table_relationships
- "Show all relationships for customers table in ecommerce database."
- "Analyze foreign key relationships for orders table in sales schema of ecommerce database."
- "Get database-wide relationship overview for ecommerce database."
- "Find all tables that reference products table in ecommerce database."
- "Show cross-schema relationships in inventory database."
- 📋 Features: Foreign key relationships (inbound/outbound), cross-schema dependencies, constraint details
- ⚠️ Required: database_name parameter must be specified
- 💡 Usage: Leave table_name empty for database-wide relationship analysis
get_user_list
- "List all database users and their roles."
- "Show user permissions for a specific database."
get_index_usage_stats
- "Analyze index usage efficiency."
- "Find unused indexes in the current database."
get_database_size_info
- "Show database capacity analysis."
- "Find the largest databases by size."
get_table_size_info
- "Show table and index size analysis."
- "Find largest tables in a specific schema."
get_vacuum_analyze_stats
- "Show recent VACUUM and ANALYZE operations."
- "List tables needing VACUUM."
get_current_database_info
- "What database am I connected to?"
- "Show current database information and connection details."
- "Display database encoding, collation, and size information."
- 📋 Features: Database name, encoding, collation, size, connection limits
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
get_table_bloat_analysis
- "Analyze table bloat in the current database."
- "Show dead tuple ratios and bloat estimates for user_logs table pattern."
- "Find tables with high bloat that need VACUUM maintenance."
- "Analyze bloat in specific schema with minimum 100 dead tuples."
- 📋 Features: Dead tuple ratios, bloat size estimates, VACUUM recommendations, pattern filtering
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
- 💡 Usage: Extension-Independent approach using pg_stat_user_tables
get_database_bloat_overview
- "Show database-wide bloat summary by schema."
- "Get high-level view of storage efficiency across all schemas."
- "Identify schemas requiring maintenance attention."
- 📋 Features: Schema-level aggregation, total bloat estimates, maintenance status
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
get_autovacuum_status
- "Check autovacuum configuration and trigger conditions."
- "Show tables needing immediate autovacuum attention."
- "Analyze autovacuum threshold percentages for public schema."
- "Find tables approaching autovacuum trigger points."
- 📋 Features: Trigger threshold analysis, urgency classification, configuration status
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
- 💡 Usage: Extension-Independent autovacuum monitoring using pg_stat_user_tables
get_autovacuum_activity
- "Show autovacuum activity patterns for the last 48 hours."
- "Monitor autovacuum execution frequency and timing."
- "Find tables with irregular autovacuum patterns."
- "Analyze recent autovacuum and autoanalyze history."
- 📋 Features: Activity patterns, execution frequency, timing analysis
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
- 💡 Usage: Historical autovacuum pattern analysis
get_running_vacuum_operations
- "Show currently running VACUUM and ANALYZE operations."
- "Monitor active maintenance operations and their progress."
- "Check if any VACUUM operations are blocking queries."
- "Find long-running maintenance operations."
- 📋 Features: Real-time operation status, elapsed time, impact level, process details
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
- 💡 Usage: Real-time maintenance monitoring using pg_stat_activity
get_vacuum_effectiveness_analysis
- "Analyze VACUUM effectiveness and maintenance patterns."
- "Compare manual VACUUM vs autovacuum efficiency."
- "Find tables with suboptimal maintenance patterns."
- "Check VACUUM frequency vs table activity ratios."
- 📋 Features: Maintenance pattern analysis, effectiveness assessment, DML-to-VACUUM ratios
- 🔧 PostgreSQL 12-17: Fully compatible, no extensions required
- 💡 Usage: Strategic VACUUM analysis using existing statistics
get_table_bloat_analysis
- "Analyze table bloat in the public schema."
- "Show tables with high dead tuple ratios in ecommerce database."
- "Find tables requiring VACUUM maintenance."
- "Check bloat for tables with more than 5000 dead tuples."
- 📋 Features: Dead tuple ratios, estimated bloat size, VACUUM recommendations
- ⚠️ Required: Specify database_name for cross-database analysis
get_database_bloat_overview
- "Show database-wide bloat summary by schema."
- "Get bloat overview for inventory database."
- "Identify schemas with highest bloat ratios."
- "Database maintenance planning with bloat statistics."
- 📋 Features: Schema-level aggregation, maintenance priorities, size recommendations
get_lock_monitoring
- "Show all current locks and blocked sessions."
- "Show only blocked sessions with granted=false filter."
- "Monitor locks by specific user with username filter."
- "Check exclusive locks with mode filter."
get_wal_status
- "Show WAL status and archiving information."
- "Monitor WAL generation and current LSN position."
get_replication_status
- "Check replication connections and lag status."
- "Monitor replication slots and WAL receiver status."
get_database_stats
- "Show comprehensive database performance metrics."
- "Analyze transaction commit ratios and I/O statistics."
- "Monitor buffer cache hit ratios and temporary file usage."
get_bgwriter_stats
- "Analyze checkpoint performance and timing."
- "Show me checkpoint performance."
- "Show background writer efficiency statistics."
- "Monitor buffer allocation and fsync patterns."
get_user_functions_stats
- "Analyze user-defined function performance."
- "Show function call counts and execution times."
- "Identify performance bottlenecks in custom functions."
- ⚠️ Requires: track_functions = pl in postgresql.conf
get_table_io_stats
- "Analyze table I/O performance and buffer hit ratios."
- "Identify tables with poor buffer cache performance."
- "Monitor TOAST table I/O statistics."
- 💡 Enhanced with: track_io_timing = on for accurate timing
get_index_io_stats
- "Show index I/O performance and buffer efficiency."
- "Identify indexes causing excessive disk I/O."
- "Monitor index cache-friendliness patterns."
- 💡 Enhanced with: track_io_timing = on for accurate timing
get_database_conflicts_stats
- "Check replication conflicts on standby servers."
- "Analyze conflict types and resolution statistics."
- "Monitor standby server query cancellation patterns."
- "Monitor WAL generation and current LSN position."
get_replication_status
- "Check replication connections and lag status."
- "Monitor replication slots and WAL receiver status."

🚀 Version-Aware Tools (Auto-Adapting)

get_io_stats (New!)
- "Show comprehensive I/O statistics." (PostgreSQL 16+ provides detailed breakdown)
- "Analyze I/O statistics."
- "Analyze buffer cache efficiency and I/O timing."
- "Monitor I/O patterns by backend type and context."
- 📈 PG16+: Full pg_stat_io with timing, backend types, and contexts
- 📊 PG12-15: Basic pg_statio_* fallback with buffer hit ratios
get_bgwriter_stats (Enhanced!)
- "Show background writer and checkpoint performance."
- 📈 PG15: Separate checkpointer and bgwriter statistics (unique feature)
- 📊 PG12-14, 16+: Combined bgwriter stats (includes checkpointer data)
get_server_info (Enhanced!)
- "Show server version and compatibility features."
- "Check server compatibility."
- "Check what MCP tools are available on this PostgreSQL version."
- "Displays feature availability matrix and upgrade recommendations."
get_all_tables_stats (Enhanced!)
- "Show comprehensive statistics for all tables." (version-compatible for PG12-17)
- "Include system tables with include_system=true parameter."
- "Analyze table access patterns and maintenance needs."
- 📈 PG13+: Tracks insertions since vacuum (n_ins_since_vacuum) for optimal maintenance scheduling
- 📊 PG12: Compatible mode with NULL for unsupported columns

🟡 Extension-Dependent Tools

get_pg_stat_statements_top_queries (Requires pg_stat_statements)
- "Show top 10 slowest queries."
- "Analyze slow queries in the inventory database."
- 📈 Version-Compatible: PG12 uses total_time → total_exec_time mapping; PG13+ uses native columns
- 💡 Cross-Version: Automatically adapts query structure for PostgreSQL 12-17 compatibility
get_pg_stat_monitor_recent_queries (Optional, uses pg_stat_monitor)
- "Show recent queries in real time."
- "Monitor query activity for the last 5 minutes."
- 📈 Version-Compatible: PG12 uses total_time → total_exec_time mapping; PG13+ uses native columns
- 💡 Cross-Version: Automatically adapts query structure for PostgreSQL 12-17 compatibility

💡 Pro Tip: All tools support multi-database operations using the database_name parameter. This allows PostgreSQL superusers to analyze and monitor multiple databases from a single MCP server instance.

Troubleshooting

Connection Issues

Check PostgreSQL server status
Verify connection parameters in .env file
Ensure network connectivity
Check user permissions

Extension Errors

Run get_server_info to check extension status
Install missing extensions:

   CREATE EXTENSION pg_stat_statements;
   CREATE EXTENSION pg_stat_monitor;

Restart PostgreSQL if needed

Configuration Issues

"No data found" for function statistics: Check track_functions setting

   SHOW track_functions;  -- Should be 'pl' or 'all'

Quick fix for managed services (AWS RDS, etc.):

   ALTER SYSTEM SET track_functions = 'pl';
   SELECT pg_reload_conf();

Missing I/O timing data: Enable timing collection

   SHOW track_io_timing;  -- Should be 'on'

Quick fix:

   ALTER SYSTEM SET track_io_timing = 'on';
   SELECT pg_reload_conf();

Apply configuration changes:
- Self-managed: Add settings to postgresql.conf and restart server
- Managed services: Use ALTER SYSTEM SET + SELECT pg_reload_conf()
- Temporary testing: Use SET parameter = value for current session
- Generate some database activity to populate statistics

Performance Issues

Use limit parameters to reduce result size
Run monitoring during off-peak hours
Check database load before running analysis

Version Compatibility Issues

For more details, see the ## Tool Compatibility Matrix

Run compatibility check first:

   # "Use get_server_info to check version and available features"

Understanding feature availability:
- PostgreSQL 16-17: All features available
- PostgreSQL 15+: Separate checkpointer stats
- PostgreSQL 14+: Parallel query tracking
- PostgreSQL 12-13: Core functionality only
If a tool shows "Not Available":
- Feature requires newer PostgreSQL version
- Tool will automatically use best available alternative
- Consider upgrading PostgreSQL for enhanced monitoring

Development

Testing & Development

# Test with MCP Inspector
./scripts/run-mcp-inspector-local.sh

# Direct execution for debugging
python -m src.mcp_postgresql_ops.mcp_main --log-level DEBUG

# Test version compatibility (requires different PostgreSQL versions)
# Modify POSTGRES_HOST in .env to point to different versions

# Run tests (if you add any)
uv run pytest

Version Compatibility Testing

The MCP server automatically adapts to PostgreSQL versions 12-17. To test across versions:

Set up test databases: Different PostgreSQL versions (12, 14, 15, 16, 17)
Run compatibility tests: Point to each version and verify tool behavior
Check feature detection: Ensure proper version detection and feature availability
Verify fallback behavior: Confirm graceful degradation on older versions

Security Notes

All tools are read-only - no data modification capabilities
Sensitive information (passwords) are masked in outputs
No direct SQL execution - only predefined queries
Follows principle of least privilege

Contributing

🤝 Got ideas? Found bugs? Want to add cool features?

We're always excited to welcome new contributors! Whether you're fixing a typo, adding a new monitoring tool, or improving documentation - every contribution makes this project better.

Ways to contribute:

🐛 Report issues or bugs
💡 Suggest new PostgreSQL monitoring features
📝 Improve documentation
🚀 Submit pull requests
⭐ Star the repo if you find it useful!

Pro tip: The codebase is designed to be super friendly for adding new tools. Check out the existing @mcp.tool() functions in mcp_main.py.

MCPO Swagger Docs

[MCPO Swagger URL] http://localhost:8003/postgresql-ops/docs

License

Freely use, modify, and distribute under the MIT License.

⭐ Other Projects

Other MCP servers by the same author:

[LogSentinelAI] LLM-Powered Log Analyzer for Security Events and Anomalies

call518 — Fri, 25 Jul 2025 11:09:27 +0000

GitHub Repo

https://github.com/call518/LogSentinelAI

Hello everyone,

After seeing how brittle and time-consuming rule-based log parsing can be in real-world environments, I set out to build LogSentinelAI, an open-source, LLM-powered log analysis tool. LLM-powered log analysis tool. Whereas traditional solutions force you to normalize logs and write rigid parsing rules, LogSentinelAI works on both structured and unstructured logs: you simply define the fields you care about, and the LLM automatically extracts, semantically analyzes, and understands context across log entries. In our Demo, we even showcase visualization with Elastic Stack.

I’d love feedback from system/security engineers, developers, and ops folks:

How accurate is field extraction on your real-world logs?

Does performance (throughput, latency) and cost feel reasonable?

Are there any security or privacy concerns I haven’t considered?

Your honest critiques and improvement ideas will be hugely valuable.
Full details and examples on Medium:
https://medium.com/@call518/logsentinelai-practical-llm-based-ai-log-analysis-for-security-engineering-fed4c941dee2

Dashboard Example

📋 JSON Output Example

LogSentinelAI - LLM-Powered Log Analyzer for Security Events and Anomalies