python-openstackmcp

The python-openstackmcp-server implements the Model Context Protocol (MCP) to expose OpenStack services to AI assistants. It provides MCP endpoints that allow an assistant to discover, request, and manage OpenStack resources across compute, images, identity, networking, and block storage through a consistent interface. Once running, you can connect an MCP-enabled assistant (e.g., Claude Desktop or another MCP client) and issue high-level prompts to perform tasks such as creating or deleting servers, listing flavors, managing images, authenticating against the cloud, configuring networks, and manipulating block storage volumes. The server relies on the OpenStack SDK under the hood to translate MCP requests into REST API calls to your OpenStack cloud.

To use it, ensure your OpenStack credentials are available via a clouds.yaml file and point the server to that file with the OS_CLIENT_CONFIG_FILE environment variable. The server exposes capabilities organized by OpenStack service (Compute, Image, Identity, Network, Block Storage), so you can request actions like provisioning a new VM, listing available flavors, or uploading an image, all through the MCP protocol. When running with Claude Desktop or similar tools, configure the MCP server as shown in the Quick Start examples to connect the AI assistant to this OpenStack MCP server.

Prerequisites:

• Python 3.10 or higher
• Access to an OpenStack cloud and a properly configured clouds.yaml file
• Optional: Claude Desktop or another MCP client for testing

Install steps (from source):

1. Clone the repository or download the package for the python-openstackmcp-server.
2. Create and activate a virtual environment:
   • Python venv: python -m venv venv
   • On Windows: venv\Scripts\activate
   • On macOS/Linux: source venv/bin/activate
3. Install dependencies (if there is a requirements file):
   • pip install -r requirements.txt
   • If no requirements file is provided, install the package and its dependencies as documented by the project (e.g., pip install -e .)
4. Ensure you have a clouds.yaml file configured for your OpenStack cloud and note its path for the OS_CLIENT_CONFIG_FILE env var.
5. Run the MCP server (see mcp_config for the command):
   • python python-openstackmcp-server

Optional: If you prefer using uvx, install uvx and run with the same module name, setting the OS_CLIENT_CONFIG_FILE environment variable accordingly.

Post-install checks:

• Verify the server starts without errors.
• Ensure the MCP client (e.g., Claude Desktop) can connect to the OpenStack MCP server and perform a simple query (e.g., list compute instances).

Environment variables and configuration tips:

• OS_CLIENT_CONFIG_FILE should point to your clouds.yaml that contains your OpenStack credentials. Example: /path/to/your/clouds.yaml
• Ensure the AWS-like or token-based authentication in your clouds.yaml matches your OpenStack deployment configuration.
• If running behind a firewall or proxy, configure network access so the MCP server can reach the OpenStack API endpoints.
• When using Claude Desktop or other MCP clients, you may need to map natural language intents to specific MCP actions (e.g., 'create a VM with flavor m1.small in network net-a').
• If you encounter authentication errors, double-check that the credentials in clouds.yaml are valid and that the identity API version matches your OpenStack deployment (typically v3).
• For debugging, run the server in a verbose/logging mode if supported by the implementation to capture request/response details between the MCP server and the OpenStack SDK.