podman-mcp-server

kunwarmahen/podman-mcp-server

3.2

If you are the rightful owner of podman-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Podman MCP Server provides container management capabilities through the Model Context Protocol, enabling seamless integration with AI tools and applications.

Tools
12
Resources
0
Prompts
0

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