MCP-OpenStack-Ops

A comprehensive MCP (Model Context Protocol) server providing OpenStack cluster management and monitoring capabilities with built-in safety controls.

MCP OpenStack Operations Server: A comprehensive MCP (Model Context Protocol) server providing OpenStack project management and monitoring capabilities with built-in safety controls and single-project scope.

- ✅Project-Scoped Operations: Every tool enforces the configuredOS_PROJECT_NAME, validating resource ownership so actions stay inside a single tenant.
- ✅Safety-Gated Writes: Modify (set_*) tooling only registers whenALLOW_MODIFY_OPERATIONS=true, keeping default deployments read-only and auditable.
- ✅90+ Purpose-Built Tools: Broad coverage across compute, networking, storage, images, identity, Heat, and Octavia load balancing tasks—all constrained to the current project.
- ✅Bulk & Filtered Actions: Instance, volume, network, image, snapshot, and keypair managers accept comma-delimited targets or filter criteria to orchestrate bulk changes intentionally.
- ✅Post-Action Feedback & Async Guidance: Mutating tools reuse a shared result handler that adds emoji status checks, asynchronous timing notes, and follow-up verification commands.
- ✅Monitoring & Usage Insights:get_service_status,get_resource_monitoring,get_usage_statistics, and quota tools surface service availability, utilization, and capacity for the active project.
- ✅Unified Instance Queries: Theget_instancetool consolidates name, ID, status, and free-form search paths with pagination plus summary/detailed modes.
- ✅Server Insight & Audit Trail: Dedicated tools expose server events, hypervisor details, availability zones, quotas, and resource ownership to speed diagnostics.
- ✅Load Balancer Management: Octavia tools cover listeners, pools, members, health monitors, flavors, quotas, and amphora operations with the same safety gates.
- ✅Connection & Deployment Flexibility: Connection caching, configurable service endpoints, Docker packaging, and bothstdio/streamable-httptransports support proxy/bastion and multi-project setups.

⚠️Compatibility Notice: This MCP server is developed and optimized forOpenStack 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.

🔧 OpenStackSDK Version Customization for Older Releases

- ✅ OpenStackEpoxy (2025.1)- Fully tested
- ✅ OpenStackDalmatian (2024.2)- Fully tested

For older OpenStack releases(Wallaby, Caracal, Bobcat, etc.), you may need to customize the OpenStackSDK version to match your environment. The SDK version must be changed inBOTH files:

RUN pip install \ 'uv>=0.8.5' \ 'mcpo>=0.0.17' \ 'fastmcp>=2.12.3' \ 'aiohttp>=3.12.0' \ 'openstacksdk==3.1.1' \ # ← Change to your required version (e.g., 3.1.1 for Wallaby) 'python-dotenv>=1.0.0'

dependencies = [ "fastmcp>=2.12.3", "openstacksdk==3.1.1", # ← Must match Dockerfile version "python-dotenv>=1.1.1", # ... other dependencies ]

docker-compose build --no-cache mcp-server docker-compose up -d

⚠️Important: BothDockerfile.MCP-Serverandpyproject.tomlmust have thesame versionto avoid dependency conflicts during container runtime.

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)

# 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"

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

New consolidatedget_instancetool 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

💡Need an OpenStack Cluster for Testing?
Check out this comprehensive guide:Tutorial: Install OpenStack Multinode Cluster /w Kolla-Ansible (Epoxy/Dalmatian)
Perfect for setting up a test environment to explore MCP-OpenStack-Ops capabilities.

# 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

# OpenStack Authentication (required) OS_AUTH_HOST=your-openstack-host OS_AUTH_PORT=5000 OS_AUTH_PROTOCOL=http # Use 'https' for production with SSL/TLS # OS_CACERT=/etc/ssl/certs/openstack-ca.pem # Required for HTTPS (optional for HTTP) 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

# Enable HTTPS protocol OS_AUTH_PROTOCOL=https OS_AUTH_HOST=your-secure-openstack-host OS_AUTH_PORT=13000 # Your HTTPS Keystone port # SSL Certificate Configuration # Option 1: Use custom CA certificate (recommended for production) OS_CACERT=/etc/ssl/certs/openstack-ca.pem # Option 2: Skip CA certificate (SSL verification disabled - insecure) # Just omit OS_CACERT - the server will warn you about insecure connection # Docker: Mount CA certificate into container # Add to docker-compose.yml volumes: # - /path/to/your/ca-cert.pem:/etc/ssl/certs/openstack-ca.pem:ro

# Start all services docker-compose up -d # Check logs docker-compose logs mcp-server docker-compose logs mcpo-proxy

{ "mcpServers": { "mcp-openstack-ops": { "command": "uvx", "args": ["--python", "3.12", "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" } } } }

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

MCP-OpenStack-Ops operates within a strictly defined project scopedetermined by theOS_PROJECT_NAMEenvironment variable. This provides complete tenant isolation and data privacy in multi-tenant OpenStack environments.

- 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

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

# Run project isolation security test python test_project_isolation.py

🔒 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!

- ✅ 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 differentOS_PROJECT_NAMEvalues:

# 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.

A complete multi-project configuration example is available atmcp-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

By default, all operations that can modify or delete OpenStack resources aredisabledfor safety:

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

Protected Operations (whenALLOW_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

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

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

- KeepALLOW_MODIFY_OPERATIONS=falsein 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 theALLOW_MODIFY_OPERATIONSsetting

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

- 🎯 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

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

- 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)

- 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

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

# 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

Editsrc/mcp_openstack_ops/mcp_main.pyto 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

Add utility functions tosrc/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

# 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())"

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

# In .env file REMOTE_AUTH_ENABLE=true REMOTE_SECRET_KEY=my-test-secret-key-12345

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

- 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_ENABLEdefaults tofalseif undefined, empty, or null. This ensures the server starts even without explicit authentication configuration.

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