Podman MCP Server

Container management made accessible through the Model Context Protocol.

Overview

The Podman MCP Server exposes container management capabilities through MCP, allowing AI tools and applications to:

• List and inspect running containers
• Start, stop, and restart containers
• Execute commands inside containers
• View container logs
• Manage container images
• Monitor container resource usage

Designed for seamless integration with the MCP Discovery Hub for automatic network discovery.

Features

Container Management

• List containers: View all running or stopped containers
• Container info: Inspect detailed container information
• Start/Stop/Restart: Control container lifecycle
• Execute commands: Run commands inside containers
• View logs: Access container logs with configurable line count
• Resource stats: Monitor CPU, memory, and I/O usage

Image Management

• List images: View all available container images
• Pull images: Download images from registries

Network Discovery

• Automatic broadcasting: Announces itself on the network via multicast
• Zero-configuration: No manual registration needed
• Multi-transport support: Works with HTTP and streamable-http

Installation

Prerequisites

• Python 3.10+
• Podman installed and running
• uv package manager (or pip)

Setup

# Clone or navigate to project
cd podman-mcp-server

# Install dependencies
uv sync

# Or with pip:
pip install -r requirements.txt

Configuration

Environment Variables

# Transport mode
MCP_TRANSPORT=http                    # http, streamable-http, or stdio (default)

# Server settings
MCP_HOST=0.0.0.0                     # Binding host
MCP_PORT=3001                         # Server port
MCP_SERVER_NAME=Podman MCP Server    # Display name

# Broadcasting (for MCP Discovery Hub)
MCP_ENABLE_BROADCAST=true            # Enable/disable broadcasting
MCP_BROADCAST_INTERVAL=30            # Seconds between announcements

.env File

Create a .env file in the project root:

MCP_TRANSPORT=http
MCP_PORT=3001
MCP_SERVER_NAME=Podman MCP Server
MCP_ENABLE_BROADCAST=true
MCP_BROADCAST_INTERVAL=30

Usage

Start in HTTP Mode (with broadcasting)

# Using environment variables
MCP_TRANSPORT=http MCP_PORT=3001 uv run main.py

# Or with .env file
uv run main.py

Start in Streamable-HTTP Mode

MCP_TRANSPORT=streamable-http MCP_PORT=3001 uv run main.py

Start in Stdio Mode (for Claude)

# Default mode, works with Claude Desktop
uv run main.py

Available Tools

Containers

List Containers

list_containers(all: bool = False)

List running containers (or all if all=true)

Example:

{
  "method": "tools/call",
  "params": {
    "name": "list_containers",
    "arguments": { "all": true }
  }
}

Container Info

container_info(container: str)

Get detailed information about a specific container

Start Container

start_container(container: str)

Start a stopped container

Stop Container

stop_container(container: str, timeout: int = 10)

Stop a running container (gracefully, with timeout in seconds)

Restart Container

restart_container(container: str)

Restart a container

Container Logs

container_logs(container: str, tail: int = 100)

Get logs from a container (last N lines)

Run Container

run_container(
  image: str,
  name: str = None,
  detach: bool = True,
  ports: List[str] = [],
  env: List[str] = [],
  volumes: List[str] = []
)

Run a new container

Example:

{
  "method": "tools/call",
  "params": {
    "name": "run_container",
    "arguments": {
      "image": "nginx:latest",
      "name": "my-webserver",
      "ports": ["8080:80"],
      "detach": true
    }
  }
}

Remove Container

remove_container(container: str, force: bool = False)

Remove a container (force if running)

Exec in Container

exec_container(container: str, command: List[str])

Execute a command inside a container

Container Stats

container_stats(container: str = None, no_stream: bool = True)

Get resource usage statistics for containers

Images

List Images

list_images(all: bool = False)

List available container images

Pull Image

pull_image(image: str)

Pull/download an image from a registry

Integration with MCP Discovery Hub

Automatic Discovery

When broadcasting is enabled, this server automatically registers with the MCP Discovery Hub:

1. Server broadcasts: Every 30 seconds, announces itself on 239.255.255.250:5353
2. Hub discovers: Discovery hub receives announcement and probes the server
3. Tools registered: All 12 container management tools become available network-wide

Manual Registration

If running without broadcasting:

# Scan for the server manually
curl -X POST http://localhost:8000/scan \
  -H "Content-Type: application/json" \
  -d '{"ports": [3001]}'

API Endpoints (When in HTTP Mode)

GET /

Server info endpoint

curl http://localhost:3001/

Response:

{
  "name": "Podman MCP Server",
  "version": "1.0.0",
  "protocol": "MCP Streamable HTTP",
  "endpoint": "/mcp"
}

POST /mcp

MCP protocol endpoint

All MCP communication happens here (initialize, tools/list, tools/call)

Use Cases

1. Container Orchestration

Use with AI tools to manage containerized applications:

"User: Start a new web server and configure it"
AI: I'll start an nginx container for you...
→ calls run_container(image="nginx", name="webserver", ports=["8080:80"])

2. Monitoring and Debugging

Check container status and logs:

"User: What's the status of my database container?"
AI: Let me check the logs and stats...
→ calls container_logs(container="postgres", tail=50)
→ calls container_stats(container="postgres")

3. Multi-Server Management

Deploy and manage containers across multiple hosts:

Host 1: Podman MCP Server (port 3001)
Host 2: Podman MCP Server (port 3001)
Host 3: MCP Discovery Hub (port 8000)
        ↓
        All containers managed from single AI interface

4. Development Workflows

Quickly spin up development environments:

"User: Set up a development database for testing"
AI: I'll create a PostgreSQL container for you...
→ calls run_container(
    image="postgres:15",
    name="dev-db",
    env=["POSTGRES_PASSWORD=devpass"]
  )

Logs

Server logs are written to podman_mcp.log:

# View logs
tail -f podman_mcp.log

# Check for errors
grep ERROR podman_mcp.log

Troubleshooting

Port Already in Use

# Use a different port
MCP_PORT=3002 uv run main.py

Broadcasting Not Working

Check multicast connectivity:

# Verify multicast is enabled
ip route show

# Check firewall
sudo firewall-cmd --add-service=mdns --permanent

Podman Connection Error

Ensure Podman is running:

# Start Podman service
systemctl start podman

# Verify connection
podman ps

Performance Considerations

• Container operations: Most operations complete within 100-500ms
• Log retrieval: Depends on log size and network speed
• Broadcasting overhead: Minimal (30-byte UDP packets every 30 seconds)
• Connection pooling: Configured with pool_size=5 for efficiency

Security

Best Practices

1. Run in isolated networks: Deploy in trusted network environments
2. Use firewall rules: Restrict access to the MCP port
3. Disable broadcasting in untrusted networks: Set MCP_ENABLE_BROADCAST=false
4. Monitor logs: Regularly check for unauthorized access attempts

Limitations

• No built-in authentication (rely on network security)
• No resource quotas (AI can run unlimited containers)
• Commands run with same privileges as Podman daemon

Consider adding a reverse proxy with authentication for production use.

Requirements

• Python 3.10+
• FastAPI
• SQLAlchemy
• FastMCP
• python-dotenv

Contributing

Improvements welcome! Areas for enhancement:

• Container networking configuration
• Image building and pushing
• Volume management
• Container health monitoring
• Network performance metrics

License

MIT License - See LICENSE file for details

Support

• Issues: Report on GitHub
• Documentation: See MCP Discovery Hub wiki
• Examples: Check examples/ directory