This server lets an LLM manage Kasm Workspaces sessions end-to-end: create, control, inspect, screenshot, command, and share them, plus browse available workspace images.
Session lifecycle — create (with optional sharing), destroy, pause, resume, and check status of Kasm sessions by ID.
Session discovery — list active sessions for the configured user, and list available workspace images.
Screenshots — capture a session as base64 or save it to a JPEG file, with optional width/height.
Remote commands — dispatch a command inside a session (with optional user/working dir); note Kasm never returns output or exit code.
View-only sharing — get a share link for a session created with enable_sharing=True.
Permission debugging — diagnose_permissions probes required API-key permissions non-destructively and reports what's missing (registered by default).
Workspace registry — connect_workspace finds a workspace by name, auto-creates/reuses a session, and runs a command (on by default, backed by a local SQLite file).
Opt-in modes — admin user/group management (KASM_ADMIN_MODE), undocumented registry/image tools (KASM_UNOFFICIAL_API), and WIP SSH command execution (KASM_SSH_ENABLED).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kasm-workspaces-mcp Create a Kasm Linux desktop session and share a view-only link."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for managing Kasm Workspaces sessions from an LLM — create/destroy/pause/resume sessions, screenshot them, dispatch commands, share view-only links, and (opt-in) manage users/groups/registries.
Written from scratch against the real, live-verified behavior of Kasm's Developer API — see docs/API_BEHAVIOR.md for what that means in practice and why it matters.
pip install -e ".[dev]" # add ".[ssh]" too for execute_kasm_command_ssh (⚠️ backlog/WIP — see docs/BACKLOG.md before using)Related MCP server: K8s MCP Server
Required environment variables:
Variable | Description |
| e.g. |
| from Kasm Admin → Access Management → API Keys (some versions: Settings → Developers) |
| the Kasm user this server acts as (UUID, with hyphens) |
API keys have no permissions by default — on the key's own Permissions
tab (not a role label shown elsewhere in the UI), grant at minimum User,
Users Auth Session, Sessions View, Sessions Modify, Images View to
cover this server's default tools. Full per-endpoint breakdown, including
KASM_ADMIN_MODE/KASM_UNOFFICIAL_API tools: docs/API_BEHAVIOR.md.
Optional:
Variable | Default | Description |
|
| comma-separated path allowlist |
|
| registers official user/group management tools |
|
| registers undocumented registry/image tools |
|
| registers |
| — | required if |
|
| |
| — | use when |
|
| registers |
|
| local SQLite cache/state file used by |
Enabling (or changing) a flag only takes effect after the MCP client
reconnects to this server — e.g. Claude Code's /mcp command, or a
restart.
Any of these can also go in a .env file in the directory you run kasm-mcp
from (see .env.example) — it's loaded automatically and never overrides a
variable already set in the real environment (e.g. by an MCP client's own
env config in .mcp.json).
If any tool call fails with "Unauthorized", ask the LLM to run
diagnose_permissions (registered by default, no setup needed). It
probes every permission this server needs — Images View, Sessions View, Users View, User + Users Auth Session, Sessions Modify —
using only safe, non-mutating calls (nothing is created, changed, or
destroyed) and reports exactly which one(s) are missing, plus where to
fix them in the Kasm admin UI. See
docs/API_BEHAVIOR.md
for the full per-endpoint permission table this is built from.
kasm-mcpOr wire it into a .mcp.json:
{
"mcpServers": {
"kasm": {
"type": "stdio",
"command": "kasm-mcp",
"env": {
"KASM_API_URL": "https://kasm.example.com",
"KASM_API_KEY": "...",
"KASM_API_SECRET": "...",
"KASM_USER_ID": "..."
}
}
}
}docs/ARCHITECTURE.md — module map and data flow
docs/API_BEHAVIOR.md — verified real Kasm API quirks
docs/SECURITY.md — the three opt-in modes and their threat models
docs/ADMIN_UNOFFICIAL.md — the undocumented registry/image module
MIT — see LICENSE.
Create a new Kasm session. Set enable_sharing=True to get a usable share_id back.
Inputs: group_id (required), image_name (required), enable_sharing.
Permanently destroy a Kasm session.
Inputs: kasm_id (required).
Dispatch a command inside a session. Kasm's API never returns output/exit_code for this call.
Inputs: command (required), kasm_id (required), user, working_dir.
List available workspace images.
Inputs: no named parameters.
Capture a screenshot of a session. Pass save_to_file to write a JPEG; otherwise returns base64.
Inputs: kasm_id (required), width, height, save_to_file.
Get the current status of a Kasm session.
Inputs: kasm_id (required).
List active sessions for the configured user.
Inputs: no named parameters.
Pause a Kasm session.
Inputs: kasm_id (required).
Resume a paused Kasm session.
Inputs: kasm_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each tool targets a distinct action or resource: lifecycle operations (create/pause/resume/destroy), status/list, share link, screenshot, command execution, and workspace listing. No two tools appear to overlap in purpose.
Tool names mostly follow verb_noun in snake_case (create_kasm_session, destroy_kasm_session, pause_kasm_session, resume_kasm_session). Minor inconsistency exists: some use 'kasm_session' while others use just 'session' (get_session_status, get_session_screenshot) and 'user_sessions' (list_user_sessions), but the pattern remains predictable.
Ten tools is a well-scoped count for a Kasm session management server. Each tool provides a meaningful operation without redundant or unnecessary functions, making it neither too thin nor too heavy.
The toolset covers the main session lifecycle (create, destroy, pause, resume, status, list) plus sharing, screenshots, command execution, and available workspaces. Minor gaps exist, such as no update/rename session or share revocation, but the core workflows for Kasm session management are complete.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
