OpenStack

openstack-mcp-server

社区项目，与 OpenStack/OpenInfra Foundation 无关。

一个模型上下文协议服务，可让 AI 助手检查 OpenStack 云。默认采用只读模式，返回内容有限，并完全通过 OpenStack 自身的设置和环境变量进行配置，因此可直接作为本地进程或容器运行，无需修改。

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

功能

• 提供 32 个只读工具，涵盖计算、镜像、块存储、网络、Keystone 目录和服务清单，以及 get_scope。
• 只有在明确启用两项设置后，才会注册写入工具。
• 项目允许列表：每个获准项目都有自己的项目范围会话。
• 每个列表都包含 limit、complete 和 next_marker；结果经过类型化处理（outputSchema、structuredContent），并限制大小。
• 错误以带有类别和操作建议的 isError 结果返回，不包含 SDK 消息、URL 或令牌。
• 默认使用 stdio；也可选择在回环地址上使用 Streamable HTTP。
• 容器镜像不包含凭据，并以非特权用户身份运行。

只读模式只是为了方便。安全边界由你配置的身份所拥有的 Keystone 角色决定；请参阅 SECURITY.md。

快速开始

该服务已列入 MCP Registry，名称为 io.github.oomchiller/openstack-mcp-server；支持注册表的客户端可直接从该处安装。手动配置：

容器（Docker MCP Toolkit 或任何 MCP 客户端）

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>

请按摘要固定镜像；发布摘要列于发布页面。 对于私有 CA，请通过 OPENSTACK_MCP_CACERT_PEM 传入证书文本。

使用 clouds.yaml 的本地进程

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

clouds.yaml 会按常规方式查找（OS_CLIENT_CONFIG_FILE、 ./clouds.yaml、~/.config/openstack/clouds.yaml、/etc/openstack/）。

配置

凭据来自 openstacksdk：通过 clouds.yaml 配置 OS_CLOUD，或使用 OS_* 变量（密码或应用凭据）。服务行为如下：

变量	默认值	含义
OPENSTACK_MCP_MODE	readonly	readonly 或 admin。
OPENSTACK_MCP_ENABLE_WRITE_TOOLS	false	与 admin 搭配时，注册写入工具。
OPENSTACK_MCP_PROJECT_IDS	空	服务可使用的项目 ID，以逗号分隔；第一个是默认值。
OPENSTACK_MCP_DEFAULT_LIMIT	50	未提供 limit 时，每次列表调用返回的项目数。
OPENSTACK_MCP_MAX_LIMIT	100	可接受的最大 limit（最高为 1000）。
OPENSTACK_MCP_MAX_RESPONSE_BYTES	524288	结果的最大大小；超过时会报错 response_too_large。
OPENSTACK_MCP_API_TIMEOUT	10	每次 OpenStack 请求的秒数；不重试。
OPENSTACK_MCP_CACERT_PEM	未设置	以 PEM 文本形式提供 CA 证书包；优先级高于 OS_CACERT。
OPENSTACK_MCP_ALLOW_INSECURE	false	允许 verify: false 或 http:// 身份验证 URL。
OPENSTACK_MCP_ENABLE_PROMPTS	true	注册提示词。
OPENSTACK_MCP_ENABLE_RESOURCES	true	注册 openstack://scope。
OPENSTACK_MCP_TRANSPORT	stdio	stdio 或 streamable-http。
OPENSTACK_MCP_HTTP_HOST / _PORT	127.0.0.1 / 8000	HTTP 绑定；路径为 /mcp。
OPENSTACK_MCP_HTTP_ALLOW_REMOTE	false	允许绑定到非环回地址。HTTP 传输没有身份验证。
OPENSTACK_MCP_LOG_LEVEL	WARNING	stderr 日志级别。SDK 日志记录器保持为 CRITICAL。

无效的 OPENSTACK_MCP_* 值会导致服务以退出代码 2 停止，并指出变量名称。缺少凭据不会导致服务停止：服务会启动，云工具会返回 [not_configured]。

运行此服务多个实例且不会为提示词名称或资源 URI 添加前缀的网关（Docker MCP Gateway），应设置 OPENSTACK_MCP_ENABLE_PROMPTS=false 和 OPENSTACK_MCP_ENABLE_RESOURCES=false。

工具

分组	工具
范围	get_scope
计算	list_servers、get_server、list_flavors
镜像	list_images、get_image
块存储	list_volumes、get_volume、list_volume_attachments、get_volume_attachment
网络	list_networks、get_network、list_subnets、get_subnet、list_ports、get_port、list_floating_ips、list_routers、get_router、list_router_interfaces、list_security_groups、get_security_group
身份	list_regions、list_domains、list_projects、list_services、list_endpoints
服务清单	list_hypervisors、list_compute_services、list_aggregates、list_network_agents、list_volume_services

身份和服务清单调用通常需要高于项目 reader 角色的权限；此类调用会返回 [forbidden]，而不是空列表。

设置 OPENSTACK_MCP_MODE=admin 和 OPENSTACK_MCP_ENABLE_WRITE_TOOLS=true 后， 会额外启用 31 个实验性写入工具（服务器、卷、镜像、网络、子网、端口、浮动 IP、路由器、安全组）。完整行为请参阅 docs/SPEC.md。

开发

uv sync --locked
uv run pytest --cov
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests

请参阅 CONTRIBUTING.md、ARCHITECTURE.md 和 DECISIONS.md。

许可证

Apache License 2.0；请参阅 LICENSE。部分代码基于 openstack-kr/python-openstackmcp-server 开发； 请参阅 NOTICE。