MCP-OpenStack-Ops

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.

---

Architecture & Internal (DeepWiki)

---

Features

• ✅ Project-Scoped Operations: Every tool enforces the configured OS_PROJECT_NAME, validating resource ownership so actions stay inside a single tenant.
• ✅ Safety-Gated Writes: Modify (set_*) tooling only registers when ALLOW_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: The get_instance tool 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 both stdio/streamable-http transports support proxy/bastion and multi-project setups.

⚠️ 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.

🔧 OpenStackSDK Version Customization for Older Releases

Officially Supported Releases:

• ✅ OpenStack Epoxy (2025.1) - Fully tested
• ✅ OpenStack Dalmatian (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 in BOTH files:

Step 1: Modify Dockerfile.MCP-Server

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'

Step 2: Modify pyproject.toml

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

Step 3: Rebuild Docker Image

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

OpenStackSDK Version Reference: | OpenStack Release | Recommended SDK Version | Notes | |-------------------|------------------------|-------| | Epoxy (2025.1) | >=3.3.0 | Current default | | Dalmatian (2024.2) | >=3.2.0 | Fully compatible | | Caracal (2024.1) | >=3.1.0 | May require testing | | Bobcat (2023.2) | >=3.0.0 | May require testing | | Wallaby (2021.1) | ==3.1.1 | Downgrade required |

⚠️ Important: Both Dockerfile.MCP-Server and pyproject.toml must have the same version to avoid dependency conflicts during container runtime.

---

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 | ✅ | Keypai