podman-mcp 0.1.0__tar.gz

podman_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edtroleis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

podman_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,414 @@
+Metadata-Version: 2.4
+Name: podman-mcp
+Version: 0.1.0
+Summary: MCP server that exposes Podman container management as tools for AI assistants
+License: MIT License
+        
+        Copyright (c) 2026 edtroleis
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Dynamic: license-file
+
+# podman-mcp
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes [Podman](https://podman.io) container management as tools for AI assistants such as [Claude](https://claude.ai), [GitHub Copilot](https://github.com/features/copilot), [ChatGPT](https://chatgpt.com), [Cursor](https://www.cursor.com) and [Windsurf](https://windsurf.com).
+
+With `podman-mcp` you can manage containers and images through natural language — no need to remember CLI flags.
+
+> "Show me all running containers"  
+> "Pull the nginx image and run it on port 8080"  
+> "Show me the last 100 log lines from myapp"
+
+---
+
+## Requirements
+
+- Python 3.10+
+- [Podman](https://podman.io/docs/installation) installed and available in `$PATH`
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI **or** any MCP-compatible client
+
+---
+
+## Installation
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/edtroleis/podman-mcp.git
+cd podman-mcp
+
+# 2. Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+```
+
+---
+
+## Client Configuration
+
+### Claude Code
+
+```bash
+claude mcp add --scope user podman-mcp -- /absolute/path/to/podman-mcp/.venv/bin/python3 /absolute/path/to/podman-mcp/server.py
+```
+
+The `--scope user` flag makes the server available across all projects, not just the current directory.
+
+Verify:
+
+```bash
+claude mcp list
+```
+
+#### Skip confirmation prompts (user scope)
+
+By default, Claude asks for confirmation before calling each tool. To allow all podman-mcp tools to run without prompts across all projects, add the following to `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__podman-mcp__*"
+    ]
+  }
+}
+```
+
+---
+
+### GitHub Copilot (VS Code)
+
+Create `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "podman-mcp": {
+      "type": "stdio",
+      "command": "/absolute/path/to/podman-mcp/.venv/bin/python3",
+      "args": ["/absolute/path/to/podman-mcp/server.py"]
+    }
+  }
+}
+```
+
+Requires VS Code 1.99+ with GitHub Copilot agent mode enabled.
+
+---
+
+### Cursor
+
+Create or edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "podman-mcp": {
+      "command": "/absolute/path/to/podman-mcp/.venv/bin/python3",
+      "args": ["/absolute/path/to/podman-mcp/server.py"]
+    }
+  }
+}
+```
+
+---
+
+### Windsurf
+
+Create or edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "podman-mcp": {
+      "command": "/absolute/path/to/podman-mcp/.venv/bin/python3",
+      "args": ["/absolute/path/to/podman-mcp/server.py"]
+    }
+  }
+}
+```
+
+---
+
+### ChatGPT and other HTTP clients
+
+Start the server in SSE mode:
+
+```bash
+python3 server.py --transport sse --host 127.0.0.1 --port 8000
+```
+
+The MCP endpoint will be available at:
+
+```
+http://127.0.0.1:8000/sse
+```
+
+Configure your client to connect to that URL as a remote MCP server.
+
+---
+
+## Using from the Terminal
+
+You can interact with podman-mcp directly from your Linux console using the Claude Code CLI — no IDE required.
+
+### Claude Code CLI
+
+Once podman-mcp is registered with `--scope user`, start an interactive session:
+
+```bash
+claude
+```
+
+Then ask naturally:
+
+```
+How many images do I have locally?
+```
+```
+Pull nginx:latest
+```
+```
+Show logs from my nexus container
+```
+```
+List all running containers
+```
+```
+Remove the alpine image
+```
+
+Claude will automatically use the podman-mcp tools to answer.
+
+### Other AI CLIs (HTTP mode)
+
+For AI tools that support remote MCP over HTTP, start the server in SSE mode first:
+
+```bash
+python3 /absolute/path/to/podman-mcp/server.py --transport sse --host 127.0.0.1 --port 8000
+```
+
+Then point your AI CLI client to:
+
+```
+http://127.0.0.1:8000/sse
+```
+
+---
+
+## Available Tools
+
+### Images
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `list_images` | List all local images | — |
+| `pull_image` | Pull an image from a registry | `image: str` |
+| `remove_image` | Remove an image | `image: str`, `force: bool` |
+| `build_image` | Build an image from a Dockerfile | `tag: str`, `dockerfile: str`, `context: str` |
+| `tag_image` | Tag an image with a new name | `source: str`, `target: str` |
+| `push_image` | Push an image to a registry | `image: str` |
+| `image_history` | Show layer history of an image | `image: str` |
+
+### Containers
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `list_containers` | List containers | `all: bool` (include stopped) |
+| `run_container` | Run a container | `image: str`, `args: str` |
+| `stop_container` | Stop a running container | `name: str` |
+| `remove_container` | Remove a container | `name: str`, `force: bool` |
+| `container_logs` | Fetch container logs | `name: str`, `tail: int` |
+| `exec_in_container` | Run a command inside a container | `name: str`, `command: str` |
+| `inspect_container` | Inspect container configuration | `name: str` |
+| `container_stats` | Show resource usage for running containers | `name: str` (empty for all) |
+
+### Networks
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `network_list` | List all networks | — |
+| `network_create` | Create a new network | `name: str` |
+| `network_remove` | Remove a network | `name: str` |
+
+### Volumes
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `volume_list` | List all volumes | — |
+| `volume_create` | Create a new volume | `name: str` |
+| `volume_remove` | Remove a volume | `name: str` |
+
+### Pods
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `pod_list` | List pods | `all: bool` (include stopped) |
+| `pod_create` | Create a new pod | `name: str` |
+| `pod_remove` | Remove a pod | `name: str`, `force: bool` |
+
+### System
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `system_info` | Podman disk usage and system stats | — |
+| `login_registry` | Login to a container registry | `registry: str`, `username: str`, `password: str` |
+
+---
+
+## Usage Examples
+
+Once registered, interact with Podman using natural language. Examples by category:
+
+### Images
+
+```
+How many images do I have locally?
+```
+```
+Pull the python:3.12-slim image from Docker Hub
+```
+```
+Build an image tagged myapp:latest from the Dockerfile in the current directory
+```
+```
+Show the layer history of the debian:latest image
+```
+```
+Tag myapp:latest as localhost:8082/myapp:1.0
+```
+```
+Push localhost:8082/myapp:1.0 to the registry
+```
+```
+Remove the alpine image
+```
+
+### Containers
+
+```
+List all running containers
+```
+```
+Show me all containers, including stopped ones
+```
+```
+Run nginx in detached mode, exposing port 8080 on the host
+```
+```
+Show the last 200 log lines from the api container
+```
+```
+What is the IP address of the db container?
+```
+```
+Show CPU and memory usage for all running containers
+```
+```
+Execute the command "df -h" inside the api container
+```
+```
+Remove all stopped containers
+```
+
+### Networks & Volumes
+
+```
+List all networks
+```
+```
+Create a network called backend-net
+```
+```
+List all volumes
+```
+```
+Create a volume called postgres-data
+```
+```
+Remove the volume named postgres-data
+```
+
+### Pods
+
+```
+List all pods, including stopped ones
+```
+```
+Create a pod called my-pod
+```
+```
+Remove the pod my-pod and all its containers
+```
+
+### System & Registry
+
+```
+Show Podman disk usage and system stats
+```
+```
+Login to localhost:8082 with my credentials
+```
+
+---
+
+## Project Structure
+
+```
+podman-mcp/
+├── server.py          # MCP server — all tools are defined here
+├── requirements.txt   # Python dependencies
+├── CONTRIBUTING.md    # How to contribute
+├── LICENSE            # MIT License
+└── README.md
+```
+
+---
+
+## Adding New Tools
+
+Open [server.py](server.py) and add a new function decorated with `@mcp.tool()`:
+
+```python
+@mcp.tool()
+def your_tool_name(param: str) -> str:
+    """Clear description — Claude uses this to decide when to call the tool."""
+    return run(f"<podman subcommand> {param}")
+```
+
+No re-registration is needed. Restart your AI client session to pick up the new tool.
+
+---
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE)