foreman-mcp-server

How to run

Using VSCode with Copilot

Start the server via uv

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:

  --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:

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):

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:

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)

# 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.

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:

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:

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:

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:

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:

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