miosa-mcp 0.2.7

MCP server that exposes MIOSA desktop control tools to Claude Code

miosa-mcp

MCP (Model Context Protocol) bridge that exposes MIOSA cloud sandboxes & desktops to any MCP-aware client (Claude Code, Cursor, Gemini CLI, etc.).

Two ways to run it

1. Hosted (recommended) — no install

MIOSA ships a public MCP endpoint at https://api.miosa.ai/api/v1/mcp. Point any MCP client at it with your msk_u_* API key as a Bearer token:

claude mcp add --transport http miosa \
  https://api.miosa.ai/api/v1/mcp \
  --header "Authorization: Bearer msk_u_your_key_here"

Full guide: docs/api/mcp-connect.md.

2. Local stdio (this Python package)

Install:

pip install miosa-mcp

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "miosa": {
      "command": "python",
      "args": ["-m", "miosa_mcp"],
      "env": {
        "MIOSA_API_KEY": "msk_u_your_key_here"
      }
    }
  }
}

Use stdio when you need to wrap the MCP layer with custom local logic, or your client doesn't yet support remote MCP. Both modes hit the same MIOSA REST API under the hood.

Get your API key at https://miosa.ai/dashboard/api-keys.

Tools

Sandbox workspaces

Use these when an agent should build inside MIOSA instead of on the user's local machine. The normal loop is: create/resume a sandbox, write files under /workspace, run commands inside the sandbox, expose a preview, snapshot or pause when done, and publish from the sandbox.

For builder-style workspaces, use a stable name and a long activity cap (timeout_sec: 86400) with an idle checkpoint/pause policy. A paused sandbox preserves the filesystem for resume. Destroy is permanent and should be a separate user choice, not the default end-of-task cleanup.

Tool	Description
sandbox_create(name?, template_id?, timeout_sec?)	Create a persistent code sandbox workspace. Use a stable name for long-lived agent projects.
sandbox_list() / sandbox_get(sandbox_id)	Inspect sandbox inventory and lifecycle state.
sandbox_pause(sandbox_id) / sandbox_resume(sandbox_id)	Stop/resume a workspace without deleting its filesystem.
sandbox_extend(sandbox_id, timeout_sec?)	Extend the activity timeout before long installs, builds, or agent tasks.
sandbox_destroy(sandbox_id)	Permanently delete a sandbox. Prefer pause unless the user asks to delete it.
sandbox_write_file(sandbox_id, path, content) / sandbox_read_file(...)	Read/write files inside the sandbox filesystem.
sandbox_list_files(sandbox_id, path?) / sandbox_upload(...)	Inspect or import files. Generated code should usually be written directly under /workspace.
sandbox_exec(sandbox_id, command, timeout?) / sandbox_python(...)	Run shell/Python inside the sandbox.
sandbox_snapshot_create(...) / sandbox_snapshot_list(...) / sandbox_snapshot_restore(...)	Checkpoint and restore workspace state.
sandbox_expose(sandbox_id, port)	Return a public HTTPS preview URL for a service running in the sandbox.
sandbox_deploy(...) / sandbox_deploy_docker(...)	Publish from the sandbox to normal MIOSA Deploy or the workspace Docker Deploy appliance.
miosa_secrets_*, miosa_network_*, miosa_audit_*	Scoped secrets, egress allowlists, and audit logs for safe agent execution.

Desktop lifecycle

Tool	Description
computer_create(name, template_type?, size?)	Create a computer and start it. Sizes: xs, small, medium, large, xl; xlarge is accepted only as a legacy alias for xl. Becomes the active computer.
computer_list()	List all computers in your tenant.
computer_destroy(computer_id?)	Permanently destroy a computer.

Desktop — Visual

Tool	Description
computer_screenshot(computer_id?)	Capture a PNG screenshot. Claude can see and reason about it.
computer_get_screen_size(computer_id?)	Get screen resolution in pixels.
computer_get_cursor_position(computer_id?)	Get current cursor x/y.

Desktop — Pointer

Tool	Description
computer_click(x, y, button?, computer_id?)	Click at coordinates.
computer_double_click(x, y, computer_id?)	Double-click at coordinates.
computer_move_cursor(x, y, computer_id?)	Move cursor without clicking.
computer_drag(from_x, from_y, to_x, to_y, computer_id?)	Click-drag between positions.
computer_scroll(direction?, clicks?, x?, y?, computer_id?)	Scroll up/down/left/right.

Desktop — Keyboard

Tool	Description
computer_type(text, computer_id?)	Type text into the focused field.
computer_key(key, computer_id?)	Press a single key (Return, Tab, Escape, etc.).
computer_hotkey(keys, computer_id?)	Press a key combo (e.g. ["ctrl", "c"]).

Clipboard

Tool	Description
computer_get_clipboard(computer_id?)	Read clipboard text.
computer_set_clipboard(text, computer_id?)	Write clipboard text.

Window Management

Tool	Description
computer_windows(computer_id?)	List open windows with IDs, titles, positions.
computer_launch(app, computer_id?)	Launch an app by name (firefox, gedit, xterm…).

Shell & Files

Tool	Description
computer_bash(command, timeout?, computer_id?)	Run a bash command; returns stdout, stderr, exit_code.
computer_write_file(path, content, computer_id?)	Write a file inside the VM.
computer_read_file(path, computer_id?)	Read a file from inside the VM.

Active Computer

All tools accept an optional computer_id. When omitted, the server uses the most recently created or accessed computer automatically. This means you can computer_create once and omit the ID for the rest of the session.

Example session

> computer_create(name="my-dev-box")
Created computer 'my-dev-box' (id=comp_abc123, status=running). This is now the active computer.

> computer_screenshot()
[PNG image of the desktop appears in Claude's context]

> computer_bash(command="ls /home")
stdout:
ubuntu
exit_code: 0

> computer_launch(app="firefox")
Launched: firefox

> computer_screenshot()
[Firefox is now open]

> computer_click(x=640, y=50)
Clicked (640, 50) button=left

> computer_type(text="https://miosa.ai")
Typed: 'https://miosa.ai'

> computer_key(key="Return")
Pressed key: Return

Development

# Install deps (requires Python 3.10+)
pip install -e ".[dev]"

# Type-check
mypy miosa_mcp/

# Lint
ruff check miosa_mcp/

Architecture

The server is a single async Python process that:

1. Reads MIOSA_API_KEY from the environment
2. Initializes an AsyncMiosa client
3. Maintains an in-process cache of AsyncComputer objects
4. Serves MCP tools over stdio (the protocol Claude Code uses)
5. Maps every tool call to the corresponding MIOSA SDK method
6. Returns screenshots as base64-encoded PNG images (MCP ImageContent)

All desktop action tools (click, type, key, etc.) call the MIOSA platform API which proxies commands through to the running VM's envd daemon at port 49983.