foreman

The foreman MCP server exposes a configurable interface to interact with a Foreman instance. It supports remote execution features, content view actions, and extensible tooling that can be integrated into AI copilots or VSCode workflows. By enabling specific features (via allowed feature lists) you can trigger Foreman jobs, inspect available templates, and manage content views through a standardized MCP resource model. The server also provides resources and tooling to discover inputs for job templates and to initiate remote executions in a controlled, allowlisted manner. The VSCode integration and Copilot Chat workflows are designed to let you list and configure prompts and resources from the Foreman-backed MCP server, while Claude Desktop can be pointed at the same MCP server for a desktop assistant experience.

Prerequisites:

• A running Foreman instance accessible from the MCP server
• uv (the MCP runner) installed on the host
• API credentials (username/password or token) with sufficient Foreman permissions

Installation steps:

1. Install uv runner if not present (example):
   • Follow the uv installation guide for your platform
2. Set up environment variables (example):
   • export FOREMAN_USERNAME=your-username
   • export FOREMAN_PASSWORD=your-password
   • Optional: export FOREMAN_CA_BUNDLE=/path/to/ca.pem
3. Start the MCP server (as shown in the README example):
   • uv run foreman-mcp-server
     --foreman-url https://foreman.example.com
     --foreman-username $FOREMAN_USERNAME
     --foreman-password $FOREMAN_PASSWORD
     --log-level debug
     --host localhost
     --port 8080
     --transport stdio
     --no-verify-ssl
4. Verify the server is reachable at http://localhost:8080/mcp (default path) and test with a small request or the MCP Inspector.

Notes:

• If your Foreman uses a custom CA, you can provide a CA bundle with --ca-bundle or FOREMAN_CA_BUNDLE, or place ca.pem in the working directory.

Tips and caveats:

• Remote Execution is opt-in: use --allowed-rex-features or FOREMAN_ALLOWED_REX_FEATURES to enable features like katello_errata_install or katello_package_install. Without this, trigger tooling will be unavailable.
• When enabling Content View Actions, specify allowed actions with --allowed-cv-actions or FOREMAN_ALLOWED_CV_ACTIONS to allow publish or other content view operations.
• For environments with custom CA certificates, you can supply a CA bundle via --ca-bundle or environment variable FOREMAN_CA_BUNDLE, or rely on a ca.pem file detected in the working directory.
• The MCP Resource model exposes an allowed_features resource at foreman://remote_execution/allowed_features when features are enabled, useful for discovering inputs and available actions.
• For VSCode integration and Copilot workflows, ensure your settings.json points to the MCP server URL (e.g., http://127.0.0.1:8080/mcp) and that the appropriate credentials are provided via headers or the environment.
• If you plan to run in containers (podman), you can mount CA bundles and pass --ca-bundle to keep certificate trust consistent.