Uyuni
About
A server to interact with the Uyuni Server API for infrastructure and configuration management.
Details
- Author
- uyuni-project
- Categories
- Cloud Service, Infrastructure
Jump to
Setup
Install Uyuni in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/uyuni-project/mcp-server-uyuni
Follow the installation instructions in the repository README, then restart your MCP client.
The Uyuni MCP Server is a Model Context Protocol (MCP) server implementation that bridges the gap between Large Language Models (LLMs) and the Uyuni configuration and infrastructure management solution.
This project allows AI agents or MCP-compliant clients (such as Gemini CLI or Claude Desktop) to securely interact with your Uyuni server. The Uyuni MCP server enables users to manage their Linux infrastructure using natural language. Instead of navigating the web UI or writing complex API scripts, you can simply ask your AI assistant to perform tasks like getting system details, checking for updates, or scheduling maintenance.
Key Capabilities This server exposes a suite of tools that allow LLMs to:
- Inspect Infrastructure: Retrieve lists of active systems and view system information.
- Manage Updates: Identify systems with pending security updates or CVEs and schedule patch applications.
- Execute Actions: Schedule patches, system updates and reboots.
It is designed to be run as a container remotely (HTTP) or locally (stdio), offering a streamlined way to integrate AI-driven automation into your system administration workflows.
- Configuring the Server
- Running the Server
- list_systems: Fetches a list of active systems from the Uyuni server, returning their names and IDs.
- get_system_details: Gets details of the specified system.
- get_system_event_history: Gets the event/action history of the specified system.
- get_system_event_details: Gets the details of the event associated with the especified server and event ID.
- find_systems_by_name: Lists systems that match the provided hostname.
- find_systems_by_ip: Lists systems that match the provided IP address.
- get_system_updates: Checks if a specific system has pending updates (relevant errata).
- summarize_system_updates: Returns low-token summary counts for pending updates of a specific system (optionaladvisory_typesfilter).
- query_system_updates: Returns paginated pending updates for a specific system with optional CVE expansion and optionaladvisory_typesfilter.
- check_all_systems_for_updates: Checks all active systems for pending updates.
- summarize_fleet_updates: Returns low-token paginated summary of systems with pending updates.
- list_systems_needing_update_for_cve: Finds systems requiring a security update for a specific CVE identifier.
- list_systems_needing_reboot: Fetches a list of systems from the Uyuni server that require a reboot.
- get_unscheduled_errata: Lists applicable and unscheduled patches for a system.
- list_activation_keys: Retrieves a list of available activation keys for bootstrapping new systems.
- list_all_scheduled_actions: Fetches a list of all scheduled, in-progress, completed, or failed actions.
- list_system_groups: Fetches a list of system groups from the Uyuni server.
- list_group_systems: Lists the systems in a system group.
- schedule_pending_updates_to_system: Checks for pending updates on a system, schedules all of them to be applied.
- schedule_specific_update: Schedules a specific update (erratum) to be applied to a system.
- add_system: Bootstraps and registers a new system with Uyuni using an activation key.
- remove_system: Decommissions and removes a system from Uyuni management.
- schedule_system_reboot: Schedules a reboot for a specified system.
- cancel_action: Cancels a previously scheduled action, such as an update or reboot.
- create_system_group: Creates a new system group in Uyuni.
- add_systems_to_group: Adds systems to a system group.
- remove_systems_from_group: Removes systems from a system group.
To use the Uyuni MCP Server, follow these two main steps:
- Configuring the Server: Set up the connection details for your Uyuni instance.
- Running the Server: Choose one of the provided methods to launch the server (e.g., as a container or a local script) and configure your MCP client how to connect to and interact with the server.
Create a file (e.g.,uyuni-config.env) to store your environment variables. You can place this file anywhere, but you must reference its path when running the server.
# Required fields # # Basic API parameters UYUNI_SERVER=https://192.168.1.124:8443 # Optional fields # # Uyuni credentials for local deployments (not required for OAuth setups) UYUNI_USER=mcp-user UYUNI_PASS=password # # Set to 'false' to disable SSL certificate verification. Defaults to 'true'. UYUNI_MCP_SSL_VERIFY=true # Set to 'true' to enable tools that perform write actions (e.g., POST requests). Defaults to 'false'. UYUNI_MCP_WRITE_TOOLS_ENABLED=false # Set the transport protocol. Can be 'stdio' (default) or 'http'. UYUNI_MCP_TRANSPORT=stdio # Host and Port to bind when using HTTP transport UYUNI_MCP_HOST=127.0.0.1 UYUNI_MCP_PORT=8080 # Final public URL to advertise UYUNI_MCP_PUBLIC_URL=http://127.0.0.1:8080 # OAuth 2.0 authorization server UYUNI_AUTH_SERVER=https://auth.example.com # Set the path for the server log file. Defaults to logging to the console. UYUNI_MCP_LOG_FILE_PATH=/var/log/mcp-server-uyuni.log # Set the logging level. Can be 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'. Defaults to 'INFO'. UYUNI_MCP_LOG_LEVEL=DEBUG # Required to bootstrap new systems into Uyuni via the add_system tool. UYUNI_SSH_PRIV_KEY="-----BEGIN OPENSSH PRIVATE KEY-----\n..." UYUNI_SSH_PRIV_KEY_PASS=""
[!WARNING]Security Note on Write Tools:EnablingUYUNI_MCP_WRITE_TOOLS_ENABLEDallows the execution of state-changing and potentially destructive actions (e.g., removing systems, applying updates). When combined withUYUNI_MCP_TRANSPORT=http, this risk is amplified, as any client with network access can perform these actions. Only enable write tools in a trusted environment.
[!WARNING]Security Note on HTTP Transport:WhenUYUNI_MCP_TRANSPORTis set tohttpbutUYUNI_AUTH_SERVERis not set, the server runs without authentication. This means any client with network access can execute commands. Only use this mode in a trusted, isolated network environment. For more details, see the Security Policy.
[!WARNING] OAuth with Uyuni requires Uyuni support forPOST /manager/api/oidcLogin. Configure Uyuni OIDC support as described below. For implementation details, seehttps://github.com/uyuni-project/uyuni/pull/11084.
TheUYUNI_SSH_PRIV_KEYvariable, used by theadd_systemtool, requires the entire private key as a single-line string. The newlines from the original key file must be replaced by the literal\nsequence.
You can generate the correct format from your key file (e.g.,~/.ssh/id_rsa) using the following command. You can then copy the output into yourconfigfile or environment variable.
awk 'NF {printf "%s\\n", $0}' ~/.ssh/id_rsa
To set it as an environment variable directly in your shell, run:
export UYUNI_SSH_PRIV_KEY=$(awk 'NF {printf "%s\\n", $0}' ~/.ssh/id_rsa)
Alternatively, you can also set environment variables instead of using a file.
Choose one of the following methods to run the server.
Option A: As a Client-Managed Container (Recommended)
With this method, the MCP client handles the lifecycle of the container. This is the easiest method for deployment, as it isolates the environment and requires no local dependencies other than a container engine (e.g., Docker).
Pre-built container images are available on the GitHub Container Registry. Refer to your MCP client's documentation for specific configuration syntax.
Replace/path/to/uyuni-config.envwith the absolute path to your configuration file. ReplaceVERSIONwith the desired release tag (e.g.,v0.2.1) or uselatest.
{ "mcpServers": { "mcp-server-uyuni": { "command": "docker", "args": [ "run", "-i", "--rm", "--env-file", "/path/to/uyuni-config.env", "ghcr.io/uyuni-project/mcp-server-uyuni:VERSION" ] } } }
{ "mcpServers": { "mcp-server-uyuni": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "UYUNI_SERVER=https://192.168.1.124:8443", "-e", "UYUNI_USER=admin", "-e", "UYUNI_PASS=admin", "ghcr.io/uyuni-project/mcp-server-uyuni:VERSION" ] } } }
This method is ideal for multi-user environments where you need a persistent, network-accessible server with OAuth 2.0 support.
First, ensure the following environment variables are set in your configuration:
UYUNI_MCP_TRANSPORT=http UYUNI_MCP_HOST=0.0.0.0 # Or a specific interface UYUNI_MCP_PORT=8080 UYUNI_MCP_PUBLIC_URL=https://mcp.example.com # Client-facing MCP base URL used for OAuth discovery UYUNI_AUTH_SERVER=https://auth.example.com
UYUNI_MCP_HOSTcontrols where the server binds.UYUNI_MCP_PUBLIC_URLcontrols the URL advertised to OAuth-capable clients. Do not set the public URL to0.0.0.0.
docker run --env-file /path/to/uyuni-config.env -p 8080:8080 ghcr.io/uyuni-project/mcp-server-uyuni:latest
Your MCP client can then connect to the server using its URL.
{ "mcpServers": { "mcp-server-uyuni": { "url": "http://127.0.0.1:8080/mcp", "type": "http" } } }
[!NOTE] The server runs on plain HTTP. For production environments, it is strongly recommended to use a reverse proxy (e.g., Nginx, Apache) to provide HTTPS encryption (TLS), handle certificates, and enhance security.
[!WARNING] UnsettingUYUNI_AUTH_SERVERin HTTP mode bypasses OAuth, enabling any client on the network to access the server. This is only intended for trusted development environments.
Option C: Running Locally withuv(for development)
If you are developing or prefer running Python directly, you can useuv.
To use the server in client-managed stdio mode, use the following configuration example:
{ "mcpServers": { "mcp-server-uyuni": { "command": "uv", "args": [ "run", "--env-file", "/path/to/uyuni-config.env", "--directory", "/path/to/your/mcp-server-uyuni", "mcp-server-uyuni" ] } } }
To run the server in standalone HTTP mode, use the following command:
uv run --env-file /path/to/uyuni-config.env --directory /path/to/your/mcp-server-uyuni mcp-server-uyuni
When running the server in HTTP mode (UYUNI_MCP_TRANSPORT=http), it is strongly recommended to secure it with an authentication layer. The server includes support for OAuth 2.0 to authenticate client requests. To enable it, set theUYUNI_AUTH_SERVERenvironment variable to your identity provider's URL.
Uyuni must be configured to trust the same identity provider as the MCP server. WhenUYUNI_AUTH_SERVERis set, the MCP server forwards the user's bearer token to Uyuni atPOST /manager/api/oidcLogin.
web.oidc.enabled = true web.oidc.idp.issuer = https://auth.example.com
If you want to set the JWKS endpoint explicitly, add:
web.oidc.idp.jwks_path = /realms/your-realm/protocol/openid-connect/certs
Ifweb.oidc.idp.jwks_pathis left unset, Uyuni resolves it from the issuer's/.well-known/openid-configurationdocument.
Uyuni also validates the expected audience and the username claim. The defaults introduced by Uyuni are:
web.oidc.jwt.audience = uyuni-server web.oidc.jwt.username_claim = preferred_username
- web.oidc.idp.issuermust match the tokenissclaim exactly.
- The forwarded token must include asubclaim.
- web.oidc.jwt.username_claimmust point to a claim whose value matches an existing active Uyuni username.
- The forwarded token must include both audiences required by this integration:mcp-server-uyunifor the MCP server anduyuni-serverfor Uyuni.
- If you changeweb.oidc.jwt.audiencein Uyuni, your identity provider must issue the matching audience value.
After updatingrhn.conf, restart the relevant Uyuni services according to your deployment procedure, then verify that:
- the token issuer matchesweb.oidc.idp.issuer
- the token audience includesuyuni-server
- the token containspreferred_usernameor your configured username claim
- the username from that claim already exists in Uyuni
Follow these practices to harden your deployment.
The Uyuni user configured viaUYUNI_USERshould have the minimum set of permissions required to perform its tasks. Avoid using highly privileged accounts likeadmin. See "Role-Based Access Control" in Uyuni documentation to fine-tune permissions.
Enabling state-changing tools withUYUNI_MCP_WRITE_TOOLS_ENABLED=trueposes a significant risk. Only enable this in trusted environments and when all other security measures, such as authentication and HTTPS, are in place.
Avoid hardcoding secrets like passwords (UYUNI_PASS) or SSH keys (UYUNI_SSH_PRIV_KEY) in your configuration files, especially if they are checked into version control. Use a secrets management system (e.g., HashiCorp Vault, cloud provider secret stores) or inject them as environment variables at runtime. Ensure configuration files containing secrets (likeuyuni-config.env) are not committed to Git.
For production environments, configure structured logging to a file for monitoring and auditing:
- SetUYUNI_MCP_LOG_FILE_PATHto a secure location (e.g.,/var/log/mcp-server-uyuni.log).
- SetUYUNI_MCP_LOG_LEVELtoINFOorWARNING. Regularly review logs for unusual or unauthorized activity.
We would love to hear from you! Any idea you want to discuss or share, please do so athttps://github.com/uyuni-project/uyuni/discussions/10562
If you encounter any bug, be so kind to open a new bug report athttps://github.com/uyuni-project/mcp-server-uyuni/issues/new?type=bug
This project is licensed under the Apache License, Version 2.0. See theLICENSEfile for details.
This is an open-source project provided "AS IS" without any warranty, express or implied. Use at your own risk. For full details, please refer to theLicensesection.
Get prescriptive CDK advice, explain CDK Nag rules, check suppressions, generate Bedrock Agent schemas, and discover AWS Solutions Constructs patterns.
Core AWS MCP server providing prompt understanding and server management capabilities.
Manage and interact with Microsoft Azure services.
An MCP Server that connects to Gemini Cloud Assist APIs, enabling you to manage and troubleshoot your Google Cloud environment using natural language.
The IBM Instana MCP server enables seamless interaction with the IBM Instana observability platform, allowing you to access real-time observability data directly within your development workflow.
Query and interact with kubernetes environments monitored by Metoro
Exposes cloud provider control and data planes to agents as self-describing, queryable and mutable data sources using SQL, minimising tool surface and token usage.
An MCP server for 1Panel, a modern Linux server operation and maintenance panel.
Automate Akamai resource actions using a conversational AI client. Requires Akamai API credentials.
Enables AI assistants to interact with Azure Kubernetes Service (AKS) clusters.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
