kde-desktop-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
KDE Desktop Automation exposes session-scoped KDE desktop operations.
Every desktop tool call requires an explicit session argument: use a managed
private session ID, or the exact value user-desktop to deliberately select
the real desktop. Defaults and environment variables do not select a target for
MCP calls.
Use session='user-desktop' to select the real user desktop explicitly for that
call. Never infer or substitute the live desktop when a private session is
missing or stopped. The live target must always be explicitly passed.
Window-targeted key, text, and normalized click input require an already-active window; activate it explicitly first. They use KWin fake input through compositor focus, so checking the window ID does not make delivery atomic to that window. Global pointer click/drag tools instead take logical desktop pixels and are not window-bound; they can move the pointer and change the active window. Live window activation/minimization and explicit pointer actions may change user focus. KWin may ignore fake-input events, so a successful tool call is not proof that an application received the action; verify with a screenshot or independent application state. Drag paths are bounded to 64 steps and must stay within the selected desktop's output geometry.
kde_desktop_observe returns a fresh window/display/pointer snapshot and the
screenshot image. Screenshot-pixel mapping is explicit when a single display is
captured; composite multi-display mapping is reported as unavailable rather than
guessed. kde_window_set_geometry is the precise KWin frame-placement path, while
kde_input_drag remains a real global pointer gesture for UI interactions.
Session IDs select a target; they are not per-client authorization tokens. MCP
clients sharing this server share the Unix user's authority over managed private
sessions, including the ability to list and stop them. kde_session_use changes
a persisted CLI default but does not affect MCP desktop calls, which always
require an explicit selector. Use session lifecycle tools only through a
coordinator authorized to manage the selected session. Media tools query the
selected session's MPRIS bus and can reveal its current media metadata; player
names must be selected explicitly. Successful control and seek calls report
request submission, not verified playback effect.
PipeWire audio tools are live-user-desktop only. They require
session='user-desktop', may reveal active application audio streams, and can
change device routing, volume, or microphone mute state. Confirm device and
application selectors with kde_audio_list first.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| kde_session_listA | List managed private KWin sessions and identify the private default. |
| kde_session_createB | Create an isolated private KWin session; never creates or attaches to the live desktop. |
| kde_session_showB | Inspect a managed private KWin session by ID. |
| kde_session_useA | Set the persisted private default for CLI clients that omit --session. This does not change MCP desktop calls, which require an explicit session. |
| kde_session_stopA | Stop a managed private session and its tracked applications. Does not affect the live desktop. On shared servers, use only through the coordinator authorized to manage that session. |
| kde_session_launchA | Launch an executable with argv inside a managed private KWin session; no shell is used. |
| kde_window_listA | List windows in a private session or explicitly selected user-desktop. |
| kde_window_findA | Find exactly one window by app ID and/or title substring; ambiguity returns candidates. |
| kde_window_waitB | Wait up to 60 seconds for a unique matching window, optionally until KWin reports fullscreen or its geometry fills a logical display. |
| kde_window_inspectA | Inspect one window using a UUID from the same selected session. |
| kde_window_activateB | Activate a selected window. user-desktop activation changes real user focus. |
| kde_window_set_minimizedA | Set a window's minimized state explicitly and verify it. Setting false restores it; live changes may change user focus. |
| kde_window_set_geometryA | Set an explicit KWin frame rectangle in logical desktop pixels and verify its effective geometry. This is window placement, not a simulated mouse drag. |
| kde_input_keyB | Send a key chord to an already-active target window; no implicit activation. |
| kde_input_typeA | Type literal text into an already-active target window; no implicit activation. |
| kde_input_clickB | Click an already-active target window at normalized window coordinates [0, 1]. |
| kde_input_click_atA | Click a global logical-desktop pixel coordinate, not a window-relative point. The point must lie on a listed display; this may move the pointer or change focus. |
| kde_input_dragB | Drag between global logical-desktop pixel coordinates. Every interpolated point must lie on a listed display; steps are limited to 1–64. Duration and start/end pauses are bounded to make real UI drag-and-drop gestures deliverable without changing their global-coordinate semantics. This can move the pointer or change the active window and is not bound to a particular window. |
| kde_pointer_positionA | Read the selected session's current pointer position without moving it. |
| kde_display_listA | List logical display geometry in the selected target session. |
| kde_media_listB | List MPRIS players registered on the selected session's D-Bus. |
| kde_media_inspectA | Read playback status, title/artist/album, current position, and duration from one explicitly selected MPRIS player. |
| kde_media_controlA | Submit play, pause, play-pause, stop, next, previous, or a relative seek to one explicitly selected MPRIS player. For seek, seconds is required, must be non-zero, and is an offset (negative rewinds). Use kde_media_seek_to when you need an absolute playback position. |
| kde_media_seek_toA | Seek one exact listed MPRIS player to an absolute position from 0 through 86400 seconds. The request is not verified; inspect the player afterward. |
| kde_audio_listA | List live PipeWire outputs, inputs, defaults, volume/mute, and active output streams. Requires session='user-desktop'. |
| kde_audio_set_defaultC | Set and verify the live default output sink or input source. |
| kde_audio_set_volumeB | Set and verify a live sink/source volume from 0 through 100 percent. |
| kde_audio_set_muteC | Explicitly mute or unmute one live sink/source and verify the result. |
| kde_audio_route_streamA | Move one live output stream to a sink after checking its exact stream ID and application name; requires session='user-desktop'. |
| kde_capabilitiesB | Report supported operations and known limitations for a selected target. |
| kde_desktop_observeB | Return a fresh desktop snapshot with windows, logical display geometry, pointer/focus context, and screenshot metadata/image content when Spectacle is available. |
| kde_screenshotB | Capture the selected desktop and return the PNG as an MCP image result. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 32 tools
Most tools are clearly partitioned by domain and action (session_*, window_*, input_*, audio_*, media_*), and descriptions actively disambiguate near-pairs like click vs click_at (window-relative vs global) and media_control vs media_seek_to (relative vs absolute). Minor residual overlap remains: kde_screenshot vs kde_desktop_observe (which also returns screenshot content), and kde_window_find/wait/list/inspect all target the same resource from different angles.
Every tool follows the same kde_<domain>_<verb>_<noun> snake_case pattern (kde_session_create, kde_audio_set_volume, kde_media_seek_to, kde_window_set_geometry). The domain prefix groups tools predictably and no mixed conventions appear.
32 tools is heavy for a single server, though the count is spread across seven genuinely distinct subsystems (sessions, windows, input, audio, media, display, screenshot) rather than being padding. It sits at the edge where an agent must scan a large surface to pick a tool, but each tool still maps to a real operation.
Coverage is broad and lifecycle-ish for sessions, audio, media, and window placement/state, but there are notable desktop-automation gaps: no window close/kill tool and no mouse scroll/wheel input, both of which are core to GUI automation and would force workarounds. Session management also lacks an explicit delete (only stop/launch).