You can run and connect to the Foreman MCP server to interact with Foreman data through a dedicated MCP interface. This server lets you expose Foreman’s functionality to MCP clients, enabling prompts, resources, and tools to be executed remotely in a controlled way.

How to use

Start the MCP server using your preferred runtime, then connect with an MCP client or editor integration to run prompts, view resources, and use tools exposed by the server. The server supports a standard transport and can be run locally or inside a container. Use the provided command to start the server, then configure your client to connect to the local MCP endpoint.

How to install

Prerequisites: you need the runtime used to start the MCP server and access to Foreman. Ensure you have access to run the server with the required arguments.

Install or prepare the runtime you will use to start the MCP server, then run the start command shown below.

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

If you need to use a custom CA certificate, you have options for providing the certificate to the server.

Option A. Use the CA bundle path via a flag or 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

Option B. Place the CA certificate as ca.pem in the working directory (automatically detected) and start the server normally.

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

Additional sections

Using containerized deployments provides a convenient way to run the MCP server with Foreman data access.

Option A. Build and run the container with standard port mapping.

podman build -t foreman-mcp-server .

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

Option B. If you need custom CA certificates with containers, mount the CA bundle or specify a path inside the container.

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

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

You can configure your VSCode MCP client to connect to the local MCP server by editing the settings file.

# 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

Open the command palette, choose MCP: List Servers, select foreman, and start the server.

Using in Copilot Chat

Open the Copilot chat, configure the MCP tools, and start prompts from the server. You can attach resources to prompts as needed.

Using MCP Inspector

For use with the MCP Inspector, start the inspector tool, point it to the MCP server URL, and connect using Streamable HTTP.

npx @modelcontextprotocol/inspector

Open http://localhost:6274 in your browser, set Type to Streamable HTTP and URL to http://localhost:8080/mcp, then click connect

## Using Claude Desktop on Linux

If you experiment with Claude Desktop, you can configure it to start the MCP server via uv using the appropriate command.

~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "foreman": { "command": "uv", "args": ["run","foreman-mcp-server", "--transport", "stdio", "--foreman-username", "login", "--foreman-password", "password/token"] } } }

To use custom CA certificates with Claude Desktop, extend the same configuration to include the CA bundle path.

~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "foreman": { "command": "uv", "args": ["run","foreman-mcp-server", "--transport", "stdio", "--foreman-username", "login", "--foreman-password", "password/token", "--ca-bundle", "/path/to/ca-bundle.pem"] } } }

Run Claude client to launch the UI, then add prompts and resources from the foreman server and configure tools as needed.

## Security and notes

Ensure credentials and CA certificates are managed securely. Use environment variables for sensitive values when possible and avoid exposing tokens in logs or command history.

## Available tools

### Start server via UV

Launch the MCP server locally using the UV runtime with the required Foreman URL, credentials, and transport options.

### Start server via Podman

Run the MCP server inside a container, exposing port 8080 and passing Foreman connection details.

### Configure custom CA certificates

Provide a CA bundle to establish trust with your Foreman instance either by a bundle path or a default ca.pem location.

### VSCode MCP integration

Configure VSCode to connect to the MCP server for listing, starting, and using prompts and resources.

### Copilot Chat integration

Open Copilot-style prompts for the MCP server and use resources attached to the conversation.

### MCP Inspector

Use MCP Inspector to connect and inspect Streamable HTTP endpoints exposed by the MCP server.

### Claude Desktop integration

Experimental integration to connect Claude Desktop with the MCP server for prompts.