Podman MCP Server

Instructions

Implementation Reference

• main_b.py:528-550 (handler)

  The handler function that implements the core logic of the 'run_container' tool by building and executing a 'podman run' command based on input parameters.

  async def run_container(self, args: Dict[str, Any]) -> Dict[str, Any]:
      image = args.get("image")
      name = args.get("name")
      detach = args.get("detach", True)
      ports = args.get("ports", [])
      env = args.get("env", [])
      volumes = args.get("volumes", [])
      
      cmd_args = ["run"]
      if detach:
          cmd_args.append("-d")
      if name:
          cmd_args.extend(["--name", name])
      for p in ports:
          cmd_args.extend(["-p", p])
      for e in env:
          cmd_args.extend(["-e", e])
      for v in volumes:
          cmd_args.extend(["-v", v])
      cmd_args.append(image)
      
      result = run_podman(cmd_args)
      return {"output": f"Started container: {result['stdout']}" if result["success"] else f"Error: {result['stderr']}"}

• main_b.py:264-303 (schema)

  The input schema for the 'run_container' tool, defining parameters such as image (required), name, detach, ports, env, and volumes.

      name="run_container",
      description="Run a new container",
      inputSchema={
          "type": "object",
          "properties": {
              "image": {
                  "type": "string",
                  "description": "Container image"
              },
              "name": {
                  "type": "string",
                  "description": "Optional container name"
              },
              "detach": {
                  "type": "boolean",
                  "description": "Run in background",
                  "default": True
              },
              "ports": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Port mappings (e.g., ['8080:80'])",
                  "default": []
              },
              "env": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Environment variables (KEY=VAL)",
                  "default": []
              },
              "volumes": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Volumes (e.g., ['/host:/container'])",
                  "default": []
              }
          },
          "required": ["image"]
      }
  ),

• main_b.py:459-472 (registration)

  Registration of the 'run_container' tool handler in the tool_handlers dictionary used in handle_tools_call.

  tool_handlers = {
      "list_containers": self.list_containers,
      "container_info": self.container_info,
      "start_container": self.start_container,
      "stop_container": self.stop_container,
      "restart_container": self.restart_container,
      "container_logs": self.container_logs,
      "run_container": self.run_container,
      "remove_container": self.remove_container,
      "exec_container": self.exec_container,
      "list_images": self.list_images,
      "pull_image": self.pull_image,
      "container_stats": self.container_stats,
  }

• main.py:200-223 (handler)

  Alternative implementation of the 'run_container' tool using the @mcp.tool decorator, which also handles schema and registration.

  @mcp.tool(title="Run container", description="Run a new container.")
  def run_container(
      image: str = Field(..., description="Container image"),
      name: str = Field(None, description="Optional name"),
      detach: bool = Field(True, description="Run in background"),
      ports: List[str] = Field(default_factory=list, description="Port mappings (e.g., ['8080:80'])"),
      env: List[str] = Field(default_factory=list, description="Environment variables (KEY=VAL)"),
      volumes: List[str] = Field(default_factory=list, description="Volumes (e.g., ['/host:/container'])"),
  ) -> str:
      args = ["run"]
      if detach:
          args.append("-d")
      if name:
          args.extend(["--name", name])
      for p in ports:
          args.extend(["-p", p])
      for e in env:
          args.extend(["-e", e])
      for v in volumes:
          args.extend(["-v", v])
      args.append(image)
  
      result = run_podman(args)
      return f"Started container: {result['stdout']}" if result["success"] else f"Error: {result['stderr']}"

• main.py:379-402 (handler)

  Duplicate implementation of the 'run_container' tool in main.py using @mcp.tool decorator.

  @mcp.tool(title="Run container", description="Run a new container.")
  def run_container(
      image: str = Field(..., description="Container image"),
      name: str = Field(None, description="Optional name"),
      detach: bool = Field(True, description="Run in background"),
      ports: List[str] = Field(default_factory=list, description="Port mappings (e.g., ['8080:80'])"),
      env: List[str] = Field(default_factory=list, description="Environment variables (KEY=VAL)"),
      volumes: List[str] = Field(default_factory=list, description="Volumes (e.g., ['/host:/container'])"),
  ) -> str:
      args = ["run"]
      if detach:
          args.append("-d")
      if name:
          args.extend(["--name", name])
      for p in ports:
          args.extend(["-p", p])
      for e in env:
          args.extend(["-e", e])
      for v in volumes:
          args.extend(["-v", v])
      args.append(image)
  
      result = run_podman(args)
      return f"Started container: {result['stdout']}" if result["success"] else f"Error: {result['stderr']}"