OrbStack MCP Server

Instructions

Implementation Reference

• src/orbstack_mcp/server.py:409-435 (handler)

  The handler function for the `orbstack_machine_create` tool, which executes the `orb` CLI command to create a new Linux machine.

  async def orbstack_machine_create(params: MachineCreateInput) -> str:
      """创建一个新的 Linux 虚拟机。
  
      支持 ubuntu, debian, fedora, arch, alpine 等多种发行版。
      在 Apple Silicon 上可通过 arch 参数指定 amd64 来运行 Intel 架构。
  
      Args:
          params: 创建参数，包括发行版名称、可选的机器名和架构
  
      Returns:
          str: 创建结果
      """
      args = ["create"]
      if params.arch:
          args.extend(["--arch", params.arch])
      args.append(params.distro)
      if params.name:
          args.append(params.name)
  
      code, stdout, stderr = await _run_orb(args, timeout=120)
      if code != 0:
          return _format_error(
              stderr,
              "可用发行版: ubuntu, debian, fedora, arch, alpine, centos, rocky, opensuse 等",
          )
      name = params.name or params.distro
      return f"Linux 机器 '{name}' 创建成功！\n{stdout}" if stdout else f"Linux 机器 '{name}' 创建成功！"

• src/orbstack_mcp/server.py:399-408 (registration)

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

  @mcp.tool(
      name="orbstack_machine_create",
      annotations={
          "title": "创建 Linux 机器",
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": False,
          "openWorldHint": False,
      },
  )

• src/orbstack_mcp/server.py:91-108 (schema)

  The Pydantic model `MachineCreateInput` defining the schema for the tool arguments.

  class MachineCreateInput(BaseModel):
      """创建 Linux 机器的输入参数"""
      model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
  
      distro: str = Field(
          ...,
          description="Linux 发行版名称，如 ubuntu, debian, fedora, arch, alpine 等",
          min_length=1,
          max_length=50,
      )
      name: Optional[str] = Field(
          default=None,
          description="机器名称，不指定则自动生成",
          max_length=100,
      )
      arch: Optional[str] = Field(
          default=None,
          description="CPU 架构：amd64 或 arm64，默认为宿主机架构",