# foreman-mcp-server
# How to run
# Using VSCode with Copilot
## Start the server via uv
```shell
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
```
Default values if not provided:
```shell
--foreman-url https://$hostname
--log-level INFO
--host '127.0.0.1'
--port 8080
--transport streamable-http
--verify-ssl
```
### Using custom CA certificates
If your Foreman instance uses a custom CA certificate, you have several options:
1. Use the `--ca-bundle` option or `FOREMAN_CA_BUNDLE` environment variable:
```shell
uv run foreman-mcp-server \
--foreman-url https://foreman.example.com \
--foreman-username $FOREMAN_USERNAME \
--foreman-password $FOREMAN_PASSWORD \
--ca-bundle /path/to/ca-bundle.pem
```
2. Place your CA certificate as `./ca.pem` in the working directory (automatically detected):
```shell
cp /path/to/ca-bundle.pem ./ca.pem
uv run foreman-mcp-server \
--foreman-url https://foreman.example.com \
--foreman-username $FOREMAN_USERNAME \
--foreman-password $FOREMAN_PASSWORD
```
## Start the server via podman
First, build the container:
```
podman build -t foreman-mcp-server .
```
Now run the container:
```shell
podman run -it -p 8080:8080 foreman-mcp-server \
--foreman-url https://my-foreman-instance.something.somewhere \
--log-level debug \
--host localhost \
--port 8080 \
--transport streamable-http
```
### Using custom CA certificates with containers
To use custom CA certificates with the container, you can either mount your CA bundle to the default `ca.pem` location (automatically detected) or specify a custom path:
**Option 1: Mount to default location (recommended)**
```shell
# Standard container or UBI9 image - mount to /app/ca.pem
podman run -it -p 8080:8080 \
-v /path/to/your-ca-bundle.pem:/app/ca.pem:ro,Z \
foreman-mcp-server \
--foreman-url https://my-foreman-instance.something.somewhere \
--transport streamable-http
**Option 2: Mount to custom location**
```shell
podman run -it -p 8080:8080 \
-v /path/to/your-ca-bundle.pem:/custom/ca.pem:ro,Z \
foreman-mcp-server \
--foreman-url https://my-foreman-instance.something.somewhere \
--ca-bundle /custom/ca.pem \
--transport streamable-http
```
## Configure VSCode
```
# settings.json
{
"mcp": {
"servers": {
"foreman": {
"url": "http://127.0.0.1:8080/mcp/sse",
"type": "http",
"headers": {
"FOREMAN_USERNAME": "login",
"FOREMAN_TOKEN": "token"
}
}
}
},
}
```
## Run VSCode client
- Press Ctrl+Shift+P
- Select MCP: List Servers command
- Select foreman
- Press Start Server
## Using in Copilot Chat
- Press Ctrl+Alt+I to open the chat
- In Configure Tools select the MCP tools only
- Prompts can be listed in the chat, e.g. /mcp.foreman.basic_hosts_pending_sec_updates_static_report
- Resources can be attached via Add Context... > MCP Resources > resource
# Using MCP Inspector
For use with mcp inspector
1) Start the inspector with `npx @modelcontextprotocol/inspector`
2) Open `http://localhost:6274` in your browser
3) Set `Type` to `Streamable HTTP` and `URL` to `http://localhost:8080/mcp`
4) Click connect
# Using Claude Desktop on Linux
Note: this is highly experimental. Tested in a virtual machine running CentOS Stream 9.
## Installation
- Follow installation steps https://github.com/bsneed/claude-desktop-fedora?tab=readme-ov-file#1-fedora-package-new
- If it doesn't launch, try `npm i -g electron
## Configuration
```
# ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"foreman": {
"command": "uv",
"args": ["--directory", "/home/$USER/foreman-mcp-server", "run","foreman-mcp-server", "--transport", "stdio", "--foreman-username", "login", "--foreman-password", "password/token"],
}
}
}
```
To use custom CA certificates with Claude Desktop:
```
# ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"foreman": {
"command": "uv",
"args": ["--directory", "/home/$USER/foreman-mcp-server", "run","foreman-mcp-server", "--transport", "stdio", "--foreman-username", "login", "--foreman-password", "password/token", "--ca-bundle", "/path/to/ca-bundle.pem"],
}
}
}
```
## Run Claude client
This will launch UI application, log in into your account. It will start and connect to the MCP server automatically.
```shell
claude-desktop
```
- Click `+` button > Add from foreman: > Select any of Prompts and Resources from the server
- Click Configuration button to select Tools from the server
# Remote Execution Features
The MCP server can trigger remote execution jobs on Foreman hosts. This functionality is **opt-in** and disabled by default for security reasons.
## Enabling Remote Execution
To enable remote execution, you must explicitly specify which remote execution features are allowed using the `--allowed-rex-features` option or the `FOREMAN_ALLOWED_REX_FEATURES` environment variable:
```shell
uv run foreman-mcp-server \
--foreman-url https://foreman.example.com \
--foreman-username $FOREMAN_USERNAME \
--foreman-password $FOREMAN_PASSWORD \
--allowed-rex-features "katello_errata_install,katello_package_install"
```
Or using the environment variable:
```shell
export FOREMAN_ALLOWED_REX_FEATURES="katello_errata_install,katello_package_install"
uv run foreman-mcp-server ...
```
## How It Works
1. **Allowlist-based security**: Only remote execution features explicitly listed in `--allowed-rex-features` can be triggered. Any attempt to use a feature not on the list will be rejected.
2. **Available features resource**: When allowed features are configured, a resource becomes available at `foreman://remote_execution/allowed_features`. This resource returns information about each allowed feature, including:
- Feature label, ID, name, and description
- Associated job template ID and name
- Any errors (e.g., if the feature doesn't exist in Foreman)
3. **Trigger tool**: The `trigger_remote_execution_job` tool is only enabled when at least one feature is allowed. To use it, the AI agent should:
1. Read the "Allowed Remote Execution Features" resource to see available features
2. Pick the appropriate feature for the task
3. Use `call_foreman_api_get` to read the feature's job template (`resource: "job_templates"`, `action: "show"`) to see what inputs it accepts
4. Call `trigger_remote_execution_job` with the feature label, search query, and appropriate inputs
## Common Remote Execution Features
Here are some commonly used remote execution feature labels:
| Feature Label | Description |
|---------------|-------------|
| `katello_errata_install` | Install errata on hosts |
| `katello_package_install` | Install packages on hosts |
| `katello_package_update` | Update packages on hosts |
| `katello_package_remove` | Remove packages from hosts |
| `katello_host_tracer_resolve` | Resolve Tracer-detected services |
To find all available features in your Foreman instance, you can use the API:
```shell
curl -u $USER:$PASSWORD https://foreman.example.com/api/remote_execution_features
```
# Content View Actions
The MCP server can publish, promote, and incrementally update content views. This functionality is **opt-in** and disabled by default for security reasons.
## Enabling Content View Actions
To enable content view actions, you must explicitly specify which actions are allowed using the `--allowed-cv-actions` option or the `FOREMAN_ALLOWED_CV_ACTIONS` environment variable:
```shell
uv run foreman-mcp-server \
--foreman-url https://foreman.example.com \
--foreman-username $FOREMAN_USERNAME \
--foreman-password $FOREMAN_PASSWORD \
--allowed-cv-actions "publish,promote,incremental_update"
```
Or using the environment variable:
```shell
export FOREMAN_ALLOWED_CV_ACTIONS="publish,promote,incremental_update"
uv run foreman-mcp-server ...
```
## How It Works
1. **Allowlist-based security**: Only content view actions explicitly listed in `--allowed-cv-actions` can be triggered. If the option is not set or empty, all content view tools are disabled.
2. **Available tools**: When specific actions are allowed, the corresponding tools become enabled:
| Action | Tool | Description |
|--------|------|-------------|
| `publish` | `publish_content_view` | Publishes a new version of a content view |
| `promote` | `promote_content_view_version` | Promotes a content view version to lifecycle environments |
| `incremental_update` | `incremental_content_view_update` | Performs an incremental update adding errata to content view versions |
3. **Usage flow**: To use the content view tools, the AI agent should:
1. Use `call_foreman_api_get` to find the content view (resource: `"content_views"`, action: `"index"`)
2. Publish a new version with `publish_content_view`
3. Promote the version with `promote_content_view_version`
4. Use `poll_task` to monitor the task progress
