# 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

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

# Install dependencies
uv sync

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

## Configuration

### Environment Variables

```env
# 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:

```env
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)

```bash
# 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

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

### Start in Stdio Mode (for Claude)

```bash
# 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:**

```json
{
  "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:**

```json
{
  "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:

```bash
# 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

```bash
curl http://localhost:3001/
```

Response:

```json
{
  "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`:

```bash
# View logs
tail -f podman_mcp.log

# Check for errors
grep ERROR podman_mcp.log
```

## Troubleshooting

### Port Already in Use

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

### Broadcasting Not Working

Check multicast connectivity:

```bash
# Verify multicast is enabled
ip route show

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

### Podman Connection Error

Ensure Podman is running:

```bash
# 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