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