create-container

Instructions

Implementation Reference

• src/docker_mcp/handlers.py:32-67 (handler)

  Main execution logic for the create-container tool: validates arguments, parses ports, pulls image if needed, runs the container using python-on-whales DockerClient, handles timeout and errors.

  async def handle_create_container(arguments: Dict[str, Any]) -> List[TextContent]:
      try:
          image = arguments["image"]
          container_name = arguments.get("name")
          ports = arguments.get("ports", {})
          environment = arguments.get("environment", {})
  
          if not image:
              raise ValueError("Image name cannot be empty")
  
          port_mappings = []
          for host_key, container_port in ports.items():
              mapping = await parse_port_mapping(host_key, container_port)
              port_mappings.append(mapping)
  
          async def pull_and_run():
              if not docker_client.image.exists(image):
                  await asyncio.to_thread(docker_client.image.pull, image)
  
              container = await asyncio.to_thread(
                  docker_client.container.run,
                  image,
                  name=container_name,
                  publish=port_mappings,
                  envs=environment,
                  detach=True
              )
              return container
  
          container = await asyncio.wait_for(pull_and_run(), timeout=DockerHandlers.TIMEOUT_AMOUNT)
          return [TextContent(type="text", text=f"Created container '{container.name}' (ID: {container.id})")]
      except asyncio.TimeoutError:
          return [TextContent(type="text", text=f"Operation timed out after {DockerHandlers.TIMEOUT_AMOUNT} seconds")]
      except Exception as e:
          return [TextContent(type="text", text=f"Error creating container: {str(e)} | Arguments: {arguments}")]

• src/docker_mcp/server.py:96-115 (schema)

  Input schema definition for the create-container tool, specifying properties for image (required), name, ports (object map), and environment (object map).

  types.Tool(
      name="create-container",
      description="Create a new standalone Docker container",
      inputSchema={
          "type": "object",
          "properties": {
              "image": {"type": "string"},
              "name": {"type": "string"},
              "ports": {
                  "type": "object",
                  "additionalProperties": {"type": "string"}
              },
              "environment": {
                  "type": "object",
                  "additionalProperties": {"type": "string"}
              }
          },
          "required": ["image"]
      }
  ),

• src/docker_mcp/server.py:156-157 (registration)

  Tool dispatch registration in the @server.call_tool() handler, routing 'create-container' calls to DockerHandlers.handle_create_container.

  if name == "create-container":
      return await DockerHandlers.handle_create_container(arguments)

• src/docker_mcp/server.py:93-147 (registration)

  Registration of the create-container tool in the @server.list_tools() function, exposing it to the MCP server.

  @server.list_tools()
  async def handle_list_tools() -> List[types.Tool]:
      return [
          types.Tool(
              name="create-container",
              description="Create a new standalone Docker container",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "image": {"type": "string"},
                      "name": {"type": "string"},
                      "ports": {
                          "type": "object",
                          "additionalProperties": {"type": "string"}
                      },
                      "environment": {
                          "type": "object",
                          "additionalProperties": {"type": "string"}
                      }
                  },
                  "required": ["image"]
              }
          ),
          types.Tool(
              name="deploy-compose",
              description="Deploy a Docker Compose stack",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "compose_yaml": {"type": "string"},
                      "project_name": {"type": "string"}
                  },
                  "required": ["compose_yaml", "project_name"]
              }
          ),
          types.Tool(
              name="get-logs",
              description="Retrieve the latest logs for a specified Docker container",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "container_name": {"type": "string"}
                  },
                  "required": ["container_name"]
              }
          ),
          types.Tool(
              name="list-containers",
              description="List all Docker containers",
              inputSchema={
                  "type": "object",
                  "properties": {}
              }
          )
      ]

• src/docker_mcp/handlers.py:12-26 (helper)

  Helper function used by the handler to parse port mappings, handling host:container and protocol (tcp/udp).

  async def parse_port_mapping(host_key: str, container_port: str | int) -> tuple[str, str] | tuple[str, str, str]:
      if '/' in str(host_key):
          host_port, protocol = host_key.split('/')
          if protocol.lower() == 'udp':
              return (str(host_port), str(container_port), 'udp')
          return (str(host_port), str(container_port))
  
      if isinstance(container_port, str) and '/' in container_port:
          port, protocol = container_port.split('/')
          if protocol.lower() == 'udp':
              return (str(host_key), port, 'udp')
          return (str(host_key), port)
  
      return (str(host_key), str(container_port))