This document provides an overview of MCP-OpenStack-Ops, a comprehensive MCP (Model Context Protocol) server that provides AI-driven OpenStack operations automation with built-in security controls and project isolation. This page covers the system's purpose, core features, high-level architecture, deployment options, and security model.
For detailed information about specific subsystems:
Sources: README.md1-40 pyproject.toml1-32
MCP-OpenStack-Ops is a production-ready MCP server that enables AI assistants (like Claude) and other clients to perform OpenStack cloud infrastructure operations through natural language or programmatic APIs. It provides comprehensive coverage across compute, network, storage, image, identity, orchestration (Heat), and load balancing (Octavia) services.
| Aspect | Description |
|---|---|
| Protocol | Model Context Protocol (MCP) for AI assistant integration |
| Target Platform | OpenStack cloud infrastructure (Epoxy 2025.1+, Dalmatian 2024.2+) |
| Primary Use Case | AI-driven infrastructure operations with safety controls |
| Deployment Model | Docker containers with stdio or HTTP transport |
| Security Model | Single-project scope with 100% tenant isolation |
Sources: README.md1-40 README.md641-800
Diagram: MCP-OpenStack-Ops Feature Hierarchy
Sources: README.md23-40 README.md100-158
| Feature Category | Key Capabilities | Safety Controls |
|---|---|---|
| Project Isolation | Every operation validates OS_PROJECT_NAMEResource ownership verification Cross-tenant access prevention | ✅ Multi-layer security ✅ Zero data leakage ✅ Shared resource filtering |
| Safety Gates | Read-only default mode Conditional tool registration Modify operations protected | ✅ ALLOW_MODIFY_OPERATIONS=false default✅ Restart required to enable writes |
| Bulk Operations | Comma-delimited targets Filter-based selection Single-step orchestration | ✅ set_instance, set_volume, set_image✅ name_contains, status filters |
| Post-Action Feedback | Emoji status indicators Async timing guidance Verification commands | ✅ handle_operation_result()✅ Real-time status tracking |
| OpenStack Coverage | 8 services, 24+ tools Instance, network, storage, image, LB, Heat | ✅ Compute, Network, Storage ✅ Image, Identity, Monitoring ✅ Orchestration, Load Balancer |
Sources: README.md23-40 README.md100-158 README.md803-847
Diagram: Complete System Architecture with Code Entities
Sources: README.md539-587 Diagram 1 from high-level systems
| Layer | Components | Primary Files | Purpose |
|---|---|---|---|
| Client Layer | Claude Desktop, Web Browser, API Client | mcp-config.json.stdio, mcp-config.json.http | User interaction through multiple interfaces |
| Container Orchestration | mcp-server, mcpo-proxy, open-webui | docker-compose.yml, Dockerfile.MCP-Server | Service deployment and networking |
| MCP Server Core | FastMCP framework, tool registry | src/mcp_openstack_ops/mcp_main.py | Tool registration and request routing |
| Operations Layer | Core functions, service modules | src/mcp_openstack_ops/functions.py, services/*.py | OpenStack operation implementation |
| Connection Management | OpenStack SDK, connection cache | src/mcp_openstack_ops/connection.py | Authentication and API access |
| OpenStack Services | Keystone, Nova, Neutron, Cinder, Glance, Heat, Octavia | N/A (external) | Infrastructure services |
Sources: README.md539-587 Diagram 2 from high-level systems
Diagram: Dual Transport Mode Architecture
Sources: README.md556-587 README.md989-1052
| Mode | Use Case | Authentication | Network Access | Configuration Complexity |
|---|---|---|---|---|
| stdio | Claude Desktop integration Local development | None required | Local only | Low - direct process spawn |
| streamable-http | Web UI (OpenWebUI) Remote API access Multi-client support | Optional Bearer token Recommended for production | Network accessible | Medium - HTTP + optional auth |
Sources: README.md556-587 README.md989-1052
Diagram: Docker Container Architecture with File Entities
Sources: README.md529-553 Diagram 1 from high-level systems
Diagram: Code Module Structure with File Paths and Key Functions
Sources: Diagram 2 from high-level systems, README.md911-972
| Component | File Path | Key Functions/Classes | Responsibility |
|---|---|---|---|
| MCP Server | src/mcp_openstack_ops/mcp_main.py | main(), FastMCP, @mcp.tool(), @conditional_tool | Tool registration, request routing, FastMCP lifecycle |
| Tool Registry | src/mcp_openstack_ops/tools/__init__.py | register_all_tools() | Automatic tool discovery and registration |
| Core Operations | src/mcp_openstack_ops/functions.py | get_service_status(), set_identity_groups(), set_roles() | High-level operation orchestration |
| Connection Manager | src/mcp_openstack_ops/connection.py | get_openstack_connection(), _connection_cache, validate_resource_ownership() | OpenStack SDK connection, caching, security validation |
| Compute Service | src/mcp_openstack_ops/services/compute.py | get_instance_details(), set_instance(), get_server_events() | Nova instance operations (1900+ lines) |
| Network Service | src/mcp_openstack_ops/services/network.py | get_network_details(), set_networks(), get_floating_ips() | Neutron network operations |
| Storage Service | src/mcp_openstack_ops/services/storage.py | get_volume_list(), set_volume(), set_snapshot() | Cinder volume operations |
| Image Service | src/mcp_openstack_ops/services/image.py | get_image_detail_list(), set_image(), set_image_members() | Glance image operations |
| Load Balancer Service | src/mcp_openstack_ops/services/load_balancer.py | get_load_balancer_status(), set_load_balancer(), set_load_balancer_listener() | Octavia LB operations |
Sources: Diagram 2 from high-level systems, README.md911-972
Diagram: Four-Layer Security Model with Code Functions
Sources: README.md641-800 Diagram 3 from high-level systems
| Security Layer | Implementation | Code Entities | Guarantee |
|---|---|---|---|
| Configuration | Environment variable OS_PROJECT_NAME | .env, connection.py | Single project scope enforcement |
| Tool Registration | @conditional_tool decorator | mcp_main.py:conditional_tool | Modify operations hidden when disabled |
| Runtime Validation | Project ID verification | connection.py:get_current_project_id() | Every operation validates project |
| Resource Ownership | Ownership validation | connection.py:validate_resource_ownership() | Block cross-tenant access |
| Secure Lookup | Project-scoped search | connection.py:find_resource_by_name_or_id() | Prevent similar-name attacks |
Sources: README.md641-800 README.md1054-1100
| Control | Default | Purpose | Restart Required |
|---|---|---|---|
ALLOW_MODIFY_OPERATIONS | false | Gate all state-changing operations | ✅ Yes - tools registered at startup |
OS_PROJECT_NAME | Required | Define single project scope | ✅ Yes - connection config |
REMOTE_AUTH_ENABLE | false | Enable Bearer token auth for HTTP mode | ❌ No - runtime check |
MCP_LOG_LEVEL | INFO | Logging verbosity | ❌ No - runtime config |
Sources: README.md803-847 README.md590-641
Diagram: Request Flow with Code Functions and API Calls
Sources: Diagram 4 from high-level systems
| Step | Command/Action | Files Involved |
|---|---|---|
| 1. Clone Repository | git clone https://github.com/call518/MCP-OpenStack-Ops | - |
| 2. Configure Environment | cp .env.example .envEdit .env with OpenStack credentials | .env |
| 3. Install Dependencies | uv sync | pyproject.toml, uv.lock |
| 4. Deploy Containers | docker-compose up -d | docker-compose.yml |
| 5. Verify Deployment | docker-compose logs mcp-server | Container logs |
| 6. Configure Client | Add to Claude Desktop config | mcp-config.json.stdio or mcp-config.json.http |
Sources: README.md443-587
Diagram: Critical Configuration Parameters in .env
Sources: README.md465-498 README.md590-641
| Parameter | Type | Default | Critical? | Purpose |
|---|---|---|---|---|
OS_AUTH_HOST | String | Required | ✅ | OpenStack Keystone host address |
OS_AUTH_PORT | Integer | 5000 | ✅ | Keystone authentication port |
OS_PROJECT_NAME | String | Required | 🔒 MOST CRITICAL | Single project scope - all operations isolated to this project |
OS_USERNAME | String | Required | ✅ | OpenStack user credentials |
OS_PASSWORD | String | Required | ✅ | OpenStack user credentials |
ALLOW_MODIFY_OPERATIONS | Boolean | false | 🚦 | Safety gate - enables/disables modify operations |
MCP_LOG_LEVEL | String | INFO | ❌ | Logging verbosity (DEBUG, INFO, WARNING, ERROR) |
FASTMCP_TYPE | String | stdio | ❌ | Transport mode (stdio for local, streamable-http for remote) |
Sources: README.md465-641
| Dependency | Version Constraint | Purpose | File Reference |
|---|---|---|---|
| fastmcp | >=2.12.3 | Model Context Protocol framework | pyproject.toml9 |
| openstacksdk | >=4.1.0,<=4.8.0 | OpenStack API client library | pyproject.toml10 |
| python-dotenv | >=1.1.1 | Environment variable management | pyproject.toml11 |
| Python | >=3.12 | Runtime environment | pyproject.toml6 |
Sources: pyproject.toml1-32
| Service | Default Port | MCP Tools | Service Module | OpenStack Component |
|---|---|---|---|---|
| Identity | 5000 | Users, projects, roles, keypairs | services/identity.py | Keystone |
| Compute | 8774 | Instances, flavors, server groups, events | services/compute.py | Nova |
| Network | 9696 | Networks, FIPs, security groups, ports | services/network.py | Neutron |
| Storage | 8776 | Volumes, snapshots, backups, QoS | services/storage.py | Cinder |
| Image | 9292 | Images, members, metadata, visibility | services/image.py | Glance |
| Placement | 8780 | Resource tracking | (embedded in monitoring) | Placement |
| Orchestration | 8004 | Heat stacks, resources | services/orchestration.py | Heat |
| Load Balancer | N/A | Listeners, pools, members, health monitors | services/load_balancer.py | Octavia |
Sources: README.md164-439 README.md590-641
For detailed information about specific aspects of MCP-OpenStack-Ops:
Sources: JSON table of contents from context
Refresh this wiki