OpenStack

openstack-mcp-server

[CI] [Release] [License]

Community project, not affiliated with OpenStack/OpenInfra Foundation.

A Model Context Protocol server that lets AI assistants inspect OpenStack clouds. It is read-only by default, bounded in what it returns, and configured entirely through OpenStack's own settings and environment variables, so it runs unchanged as a local process or a container.

flowchart LR    AI[MCP client] <-->|stdio / Streamable HTTP| Server[openstack-mcp-server]    Server <-->|openstacksdk| Cloud[OpenStack APIs]

Features

• 32 read tools for compute, images, block storage, networking, the Keystone catalog and service inventory, plus get_scope.
• Write tools are not registered unless explicitly enabled by two settings.
• Project allowlist: each allowed project gets its own project-scoped session.
• Every list has limit, complete and next_marker; results are typed (outputSchema, structuredContent) and capped in size.
• Errors are isError results with a category and an action, without SDK messages, URLs or tokens.
• stdio by default; Streamable HTTP on loopback as an option.
• Container image without credentials, running as an unprivileged user.

The read-only mode is a convenience. The security boundary is the Keystone role of the identity you configure; see SECURITY.md.

Quick start

The server is listed in the MCP Registry as io.github.oomchiller/openstack-mcp-server; registry-aware clients can install it from there. Manual setup:

Container (Docker MCP Toolkit or any MCP client)

docker run --rm -i \  -e OS_AUTH_URL=https://keystone.example.com:5000/v3 \  -e OS_USERNAME=mcp-reader -e OS_PASSWORD \  -e OS_USER_DOMAIN_NAME=Default -e OS_PROJECT_ID=0123456789abcdef0123456789abcdef \  -e OS_REGION_NAME=RegionOne \  ghcr.io/oomchiller/openstack-mcp-server@sha256:<digest>

Pin the image by digest; release digests are listed on the releases page. For a private CA, pass the certificate text in OPENSTACK_MCP_CACERT_PEM.

Local process with clouds.yaml

{  "mcpServers": {    "openstack": {      "command": "uvx",      "args": ["--from", "git+https://github.com/oomchiller/[email protected]", "openstack-mcp-server"],      "env": { "OS_CLOUD": "mycloud" }    }  }}

clouds.yaml is found the usual way (OS_CLIENT_CONFIG_FILE, ./clouds.yaml, ~/.config/openstack/clouds.yaml, /etc/openstack/).

Configuration

Credentials come from openstacksdk: OS_CLOUD with clouds.yaml, or OS_* variables (password or application credentials). Server behaviour:

An invalid OPENSTACK_MCP_* value stops the server with exit code 2 and names the variable. Missing credentials do not: the server starts, and cloud tools return [not_configured].

Gateways that run several instances of this server and do not prefix prompt names or resource URIs (Docker MCP Gateway) should set OPENSTACK_MCP_ENABLE_PROMPTS=false and OPENSTACK_MCP_ENABLE_RESOURCES=false.

Tools

Identity and service inventory usually need more than a project reader role; such calls fail with [forbidden] rather than returning empty lists.

With OPENSTACK_MCP_MODE=admin and OPENSTACK_MCP_ENABLE_WRITE_TOOLS=true, 31 experimental write tools are added (servers, volumes, images, networks, subnets, ports, floating IPs, routers, security groups). See docs/SPEC.md for the full behaviour.

Development

uv sync --lockeduv run pytest --covuv run ruff check . && uv run ruff format --check .uv run mypy src tests

See CONTRIBUTING.md, ARCHITECTURE.md and DECISIONS.md.

License

Apache License 2.0; see LICENSE. Parts of the code started in openstack-kr/python-openstackmcp-server; see NOTICE.