io.github.manusa/podman-mcp-server

Official

by manusa · Go

A Model Context Protocol (MCP) server for container runtimes (Podman and Docker)

MCP server for managing container runtimes including Podman and Docker.

Topics

container-runtimecontainerscontextdockermcpmodelmodel-context-protocolpodmanprotocol

README.md10 KBView on GitHub

Podman MCP Server

✨ Features <a id="features"></a>

A powerful and flexible MCP server for container runtimes supporting Podman and Docker.

🚀 Getting Started <a id="getting-started"></a>

Claude Desktop

Using npx

If you have npm installed, this is the fastest way to get started with podman-mcp-server on Claude Desktop.

Open your claude_desktop_config.json and add the mcp server to the list of mcpServers:

json

{
  "mcpServers": {
    "podman": {
      "command": "npx",
      "args": [
        "-y",
        "podman-mcp-server@latest"
      ]
    }
  }
}

VS Code / VS Code Insiders

Install the Podman MCP server by clicking one of the following links:

Alternatively, you can install the extension manually by running the following command:

shell

# For VS Code
code --add-mcp '{"name":"podman","command":"npx","args":["-y","podman-mcp-server@latest"]}'
# For VS Code Insiders
code-insiders --add-mcp '{"name":"podman","command":"npx","args":["-y","podman-mcp-server@latest"]}'

Goose CLI

Goose CLI is the easiest (and cheapest) way to get rolling with artificial intelligence (AI) agents.

Using npm

If you have npm installed, this is the fastest way to get started with podman-mcp-server.

Open your goose config.yaml and add the mcp server to the list of mcpServers:

yaml

extensions:
  podman:
    command: npx
    args:
      - -y
      - podman-mcp-server@latest

📚 Documentation <a id="documentation"></a>

For detailed setup guides, configuration reference, and feature specifications, see the Documentation.

🎥 Demos <a id="demos"></a>

⚙️ Configuration <a id="configuration"></a>

The Podman MCP server can be configured using command line (CLI) arguments.

You can run the CLI executable either by using npx or by downloading the latest release binary.

shell

# Run the Podman MCP server using npx (in case you have npm installed)
npx podman-mcp-server@latest --help

shell

# Run the Podman MCP server using the latest release binary
./podman-mcp-server --help

Configuration Options

Option	Description
`--port`, `-p`	Starts the MCP server in HTTP mode with Streamable HTTP at `/mcp` and SSE at `/sse` endpoints.
`--output-format`, `-o`	Output format for list commands: `text` (default, human-readable table) or `json`.
`--podman-impl`	Podman implementation to use. Auto-detects if not specified.
`--sse-port`	Deprecated. Use `--port` instead. Starts the MCP server in SSE-only mode.
`--sse-base-url`	Deprecated. SSE public base URL to use when sending the endpoint message.

Transport Modes

The server supports multiple transport modes:

STDIO mode (default) - Communicates via standard input/output
HTTP mode (--port) - Modern HTTP transport with both Streamable HTTP and SSE endpoints
SSE-only mode (--sse-port) - Legacy Server-Sent Events transport (deprecated)

shell

# Start HTTP server on port 8080 (Streamable HTTP at /mcp and SSE at /sse)
podman-mcp-server --port 8080

# Legacy SSE-only server on port 8080 (deprecated, use --port instead)
podman-mcp-server --sse-port 8080

Podman Implementations

The server supports multiple Podman backend implementations:

Implementation	Description	Priority
`api`	Podman REST API via Unix socket	100 (preferred)
`cli`	Podman/Docker CLI wrapper	50 (fallback)

By default, the server auto-detects the best available implementation. The api implementation is preferred when a Podman socket is available, otherwise the cli implementation is used as a fallback.

Use the --podman-impl flag to force a specific implementation:

shell

# Force CLI implementation
podman-mcp-server --podman-impl=cli

# Force API implementation (requires Podman socket)
podman-mcp-server --podman-impl=api

The api implementation communicates directly with the Podman REST API via Unix socket, while the cli implementation shells out to the podman or docker binary.

🛠️ Tools <a id="tools"></a>

<details> <summary>Container</summary>

container_inspect - Displays the low-level information and configuration of a Docker or Podman container with the specified container ID or name
- name (string) (required) - Docker or Podman container ID or name to display the information
container_list - Prints out information about the running Docker or Podman containers
container_logs - Displays the logs of a Docker or Podman container with the specified container ID or name
- name (string) (required) - Docker or Podman container ID or name to display the logs
container_remove - Removes a Docker or Podman container with the specified container ID or name (rm)
- name (string) (required) - Docker or Podman container ID or name to remove
container_run - Runs a Docker or Podman container with the specified image name
- environment (array) - Environment variables to set in the container. Format: <key>=<value>. Example: FOO=bar. (Optional, add only to set environment variables)
- imageName (string) (required) - Docker or Podman container image name to run
- ports (array) - Port mappings to expose on the host. Format: <hostPort>:<containerPort>. Example: 8080:80. (Optional, add only to expose ports)
container_stop - Stops a Docker or Podman running container with the specified container ID or name
- name (string) (required) - Docker or Podman container ID or name to stop

</details> <details> <summary>Image</summary>

image_build - Build a Docker or Podman image from a Dockerfile, Podmanfile, or Containerfile
- containerFile (string) (required) - The absolute path to the Dockerfile, Podmanfile, or Containerfile to build the image from
- imageName (string) - Specifies the name which is assigned to the resulting image if the build process completes successfully (--tag, -t)
image_list - List the Docker or Podman images on the local machine
image_pull - Copies (pulls) a Docker or Podman container image from a registry onto the local machine storage
- imageName (string) (required) - Docker or Podman container image name to pull
image_push - Pushes a Docker or Podman container image, manifest list or image index from local machine storage to a registry
- imageName (string) (required) - Docker or Podman container image name to push
image_remove - Removes a Docker or Podman image from the local machine storage
- imageName (string) (required) - Docker or Podman container image name to remove

</details> <details> <summary>Network</summary>

network_list - List all the available Docker or Podman networks

</details> <details> <summary>Volume</summary>

volume_list - List all the available Docker or Podman volumes

</details>

🧑‍💻 Development <a id="development"></a>

Running with mcp-inspector

Compile the project and run the Podman MCP server with mcp-inspector to inspect the MCP server.

shell

# Compile the project
make build
# Run the Podman MCP server with mcp-inspector
npx @modelcontextprotocol/inspector@latest $(pwd)/podman-mcp-server

mcp-name: io.github.manusa/podman-mcp-server

Install

claude_desktop_config.json

{
  "mcpServers": {
    "podman-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "podman-mcp-server@0.0.15"
      ]
    }
  }
}