Podman MCP Server

Instructions

Implementation Reference

• main.py:164-167 (handler)

  Handler function for container_info tool decorated with @mcp.tool for automatic registration and schema via Pydantic Field. Executes 'podman inspect' on the container.

  @mcp.tool(title="Container info", description="Inspect a container by name or ID.")
  def container_info(container: str = Field(..., description="Container name or ID")) -> str:
      result = run_podman(["inspect", container])
      return result["stdout"] if result["success"] else f"Error: {result['stderr']}"

• main_b.py:501-504 (handler)

  Async class method handler for the container_info tool. Extracts container from args, runs 'podman inspect', returns result in dict format.

  async def container_info(self, args: Dict[str, Any]) -> Dict[str, Any]:
      container = args.get("container")
      result = run_podman(["inspect", container])
      return {"output": result["stdout"] if result["success"] else f"Error: {result['stderr']}"}

• main_b.py:186-195 (schema)

  Explicit JSON schema for container_info tool input, defining required 'container' string parameter.

  inputSchema={
      "type": "object",
      "properties": {
          "container": {
              "type": "string",
              "description": "Container name or ID"
          }
      },
      "required": ["container"]
  }

• main_b.py:459-472 (registration)

  Registration dictionary mapping 'container_info' tool name to its handler method.

  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_b.py:183-196 (registration)

  Tool object registration in the tools list including name, description, and schema for container_info.

  Tool(
      name="container_info",
      description="Inspect a container by name or ID",
      inputSchema={
          "type": "object",
          "properties": {
              "container": {
                  "type": "string",
                  "description": "Container name or ID"
              }
          },
          "required": ["container"]
      }
  ),

• main_b.py:50-72 (helper)

  Helper function used by container_info to execute podman commands and handle output/errors.

  def run_podman(args: List[str]) -> Dict[str, Any]:
      """Run a podman command and capture output"""
      try:
          cmd = ["podman"] + args
          logger.info(f"Running command: {' '.join(cmd)}")
          result = subprocess.run(
              cmd,
              capture_output=True,
              text=True,
              timeout=30
          )
          return {
              "success": result.returncode == 0,
              "stdout": result.stdout.strip(),
              "stderr": result.stderr.strip(),
              "returncode": result.returncode,
          }
      except subprocess.TimeoutExpired:
          logger.error("Command timed out")
          return {"success": False, "stdout": "", "stderr": "Command timed out", "returncode": -1}
      except Exception as e:
          logger.error(f"Command error: {e}")
          return {"success": False, "stdout": "", "stderr": str(e), "returncode": -1}