orbstack_docker_run

Create and run Docker containers with port mapping, volume mounts, and environment variable configuration through OrbStack MCP Server.

Instructions

创建并运行一个新的 Docker 容器。

支持端口映射、卷挂载、环境变量等配置。

Args: params: 容器运行参数

Returns: str: 容器 ID 或运行输出

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Implementation Reference

src/orbstack_mcp/server.py:689-730 (handler)

The implementation of the `orbstack_docker_run` tool. It constructs the docker command arguments and executes them using `_run_docker`.

async def orbstack_docker_run(params: DockerRunInput) -> str:
    """创建并运行一个新的 Docker 容器。

    支持端口映射、卷挂载、环境变量等配置。

    Args:
        params: 容器运行参数

    Returns:
        str: 容器 ID 或运行输出
    """
    args = ["run"]
    if params.detach:
        args.append("-d")
    if params.name:
        args.extend(["--name", params.name])
    if params.platform:
        args.extend(["--platform", params.platform])
    if params.ports:
        for port in params.ports:
            args.extend(["-p", port])
    if params.volumes:
        for vol in params.volumes:
            args.extend(["-v", vol])
    if params.env:
        for e in params.env:
            args.extend(["-e", e])
    args.append(params.image)
    if params.command:
        args.extend(params.command.split())

    code, stdout, stderr = await _run_docker(args, timeout=120)
    if code != 0:
        return _format_error(stderr)
    container_id = stdout[:12] if len(stdout) >= 12 else stdout
    display_name = params.name or container_id
    return f"容器 '{display_name}' 已启动\n容器ID: {container_id}"


@mcp.tool(
    name="orbstack_docker_stop",
    annotations={

src/orbstack_mcp/server.py:679-688 (registration)

The MCP tool registration for `orbstack_docker_run` using the `@mcp.tool` decorator.

@mcp.tool(
    name="orbstack_docker_run",
    annotations={
        "title": "运行 Docker 容器",
        "readOnlyHint": False,
        "destructiveHint": False,
        "idempotentHint": False,
        "openWorldHint": True,
    },
)

src/orbstack_mcp/server.py:173-200 (schema)

The `DockerRunInput` schema definition using Pydantic, which defines the input parameters for the `orbstack_docker_run` tool.

class DockerRunInput(BaseModel):
    """运行 Docker 容器的输入参数"""
    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")

    image: str = Field(
        ...,
        description="Docker 镜像名称，如 nginx:latest, ubuntu:22.04",
        min_length=1,
    )
    name: Optional[str] = Field(
        default=None,
        description="容器名称",
    )
    ports: Optional[List[str]] = Field(
        default=None,
        description="端口映射列表，如 ['8080:80', '443:443']",
    )
    volumes: Optional[List[str]] = Field(
        default=None,
        description="卷挂载列表，如 ['/host/path:/container/path']",
    )
    env: Optional[List[str]] = Field(
        default=None,
        description="环境变量列表，如 ['KEY=VALUE']",
    )
    detach: bool = Field(
        default=True,
        description="是否后台运行，默认为 True",

OrbStack MCP Server