kitty-mcp-server
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., "@kitty-mcp-server open a new tab and run htop"
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.
kitty-mcp-server
MCP server for controlling the kitty terminal emulator.
Exposes 40 tools for managing kitty windows, tabs, layouts, text, appearance, and more via the Model Context Protocol. Communicates with kitty through its remote control protocol using the kitten CLI.
Prerequisites
kitty terminal emulator with remote control enabled
Node.js 20+
Related MCP server: iterm2-mcp
Installation
npm install
npm run buildkitty.conf setup
Add these lines to your ~/.config/kitty/kitty.conf:
allow_remote_control yes
listen_on unix:/tmp/kitty-{kitty_pid}Restart kitty after making changes.
Configuration for Claude Code
Option 1: Running inside kitty (auto-detects socket)
Add to .claude/settings.json:
{
"mcpServers": {
"kitty": {
"command": "node",
"args": ["/path/to/kitty-mcp-server/dist/index.js"]
}
}
}When the MCP server runs inside a kitty window, it automatically picks up the KITTY_LISTEN_ON environment variable.
Option 2: Fixed socket path
{
"mcpServers": {
"kitty": {
"command": "node",
"args": ["/path/to/kitty-mcp-server/dist/index.js"],
"env": {
"KITTY_MCP_SOCKET": "unix:/tmp/kitty-12345"
}
}
}
}Environment variables
Variable | Description |
| Override the kitty remote control socket path. Takes highest priority. |
| Set automatically by kitty inside its windows. Used as fallback when |
| Override the kitty CLI binary name or path. Default: |
| Password for kitty remote control authentication, if configured. |
Tools
Discovery (read-only inspection)
kitty_ls-- list all OS windows, tabs, and windows as a JSON treekitty_get_text-- retrieve text content from a window (screen, scrollback, selection, last command output)kitty_get_colors-- get terminal color definitionskitty_select_window-- visually select a window with overlay labels
Window Management
kitty_launch-- launch a new process in a window, tab, or OS windowkitty_close_window-- close windowskitty_focus_window-- focus a windowkitty_resize_window-- resize a window within its layoutkitty_detach_window-- move windows to a different tab or OS windowkitty_set_window_title-- set window title
Tab Management
kitty_close_tab-- close tabskitty_focus_tab-- focus a tabkitty_set_tab_title-- set tab titlekitty_set_tab_color-- change tab bar colorskitty_detach_tab-- move tabs to a different OS window
Text / Input
kitty_send_text-- send text to windowskitty_send_key-- send key presses to windows
Scroll
kitty_scroll-- scroll window content (lines, pages, prompts, start/end)
Appearance
kitty_set_colors-- set terminal colorskitty_set_font_size-- set font sizekitty_set_spacing-- set padding and marginskitty_set_background_opacity-- set background opacitykitty_disable_ligatures-- control ligature rendering
Layout
kitty_goto_layout-- switch to a specific layoutkitty_last_used_layout-- toggle to the previous layoutkitty_set_enabled_layouts-- set which layouts are available for cycling
Markers
kitty_create_marker-- highlight text matching a patternkitty_remove_marker-- remove markers from a window
System
kitty_run-- run a program and get its outputkitty_action-- run a mappable kitty actionkitty_kitten-- run a kitten (kitty extension)kitty_load_config-- reload kitty configurationkitty_signal_child-- send Unix signals to foreground processeskitty_env-- change environment variables for new windowskitty_set_user_vars-- set user variables on windowskitty_resize_os_window-- resize, fullscreen, or hide OS windows
Composite (multi-step operations)
kitty_dump_scrollback-- dump scrollback to a temp file with paginationkitty_get_tab_text-- get text from all windows in a tab in one call
Utility
kitty_clear_cache-- clear the MCP server internal cachekitty_health_check-- verify kitty connectivity and server status
License
MIT
Available Tools
40 toolskitty_actionA
Run a mappable kitty action in the specified window. Actions are the same action names used in kitty.conf key mappings (e.g. "scroll_line_down", "copy_to_clipboard", "new_tab"). Arguments are space-separated within the action string.
Inputs: action (required), self, match, no_response.
kitty_clear_cacheA
Clear the MCP server internal cache. Useful if you suspect stale data from cached ls or get-colors results.
Inputs: no named parameters.
kitty_close_tabA
Close the specified kitty tabs. If no match expression is provided, the active tab is closed.
Inputs: self, match, ignore_no_match.
kitty_close_windowA
Close the specified kitty windows. If no match expression is provided, the active window is closed.
Inputs: self, match, ignore_no_match.
kitty_create_markerA
Create a marker that highlights text matching a pattern in a kitty window. Marker types: "text"/"itext" for literal matches, "regex"/"iregex" for regex matches, "function" for custom Python functions. Color groups 1-3 use different highlight colors as configured in kitty.conf.
Inputs: marker_spec (required), self, match.
kitty_detach_tabA
Detach tabs and move them to a different or new OS window. By default, detached tabs are moved to a new OS window. Use target_tab to specify a destination OS window.
Inputs: self, match, target_tab.
kitty_detach_windowA
Detach windows and move them to a different tab or a new OS window. By default, detached windows are moved to a new OS window. Use target_tab to specify a destination tab, or "new" to create a new tab.
Inputs: self, match, target_tab, stay_in_tab.
kitty_disable_ligaturesA
Control ligature rendering for specified kitty windows/tabs. "never" shows ligatures normally, "always" disables them everywhere, "cursor" disables them only under the cursor.
Inputs: strategy (required), all, match, match_tab.
kitty_dump_scrollbackA
Dump a window's full scrollback to a temp file and read it back with pagination. Solves the problem of scrollback buffers too large to return in a single response. First call dumps and returns a page; follow-up calls with file_path paginate through the dump without re-fetching from kitty.
Inputs: ansi, limit, match, extent, +2 more.
kitty_envA
Change environment variables seen by newly launched kitty windows. Use "NAME=VALUE" to set a variable, or just "NAME" (without =) to unset it.
Inputs: env (required).
kitty_focus_tabA
Focus the specified kitty tab. The active window in that tab will be focused.
Inputs: match, no_response.
kitty_focus_windowB
Focus the specified kitty window, bringing it to the foreground. If no match expression is provided, the command window is focused.
Inputs: match, no_response.
kitty_get_colorsA
Get terminal color definitions for a kitty window. Returns color names and hex values in kitty.conf format (e.g. "background #1e1e2e"). Use --configured to get the original kitty.conf colors instead of any runtime overrides. Results are cached for 10 seconds.
Inputs: match, configured.
kitty_get_tab_textA
Get text content from ALL windows in a specific tab in a single call. Combines kitty_ls + multiple kitty_get_text calls. Returns text from every window in the tab with per-window headers showing ID, title, CWD, PID, and dimensions. Useful for understanding what is happening across split panes or monitoring multiple processes.
Inputs: ansi, match, extent, max_lines_per_window.
kitty_get_textA
Retrieve text content from a kitty window. Supports multiple extent modes: "screen" (visible content), "all" (screen + scrollback), "selection" (selected text), "last_cmd_output" (output of most recent command), and more. When extent is "all", output is truncated to max_lines (keeping most recent lines) to prevent overwhelming context.
Inputs: ansi, self, match, extent, +4 more.
kitty_goto_layoutA
Switch to a specific window layout in the active or specified tab. Valid layouts: fat, grid, horizontal, splits, stack, tall, vertical. Layout names can include options after a colon (e.g. "tall:bias=70").
Inputs: layout (required), match.
kitty_health_checkA
Perform a health check of the kitty MCP server. Verifies that the kitty CLI is accessible and all server subsystems are operational.
Inputs: no named parameters.
kitty_kittenB
Run a kitten (kitty extension) over the specified windows. The kitten can be a builtin name or a path to a Python file containing a custom kitten.
Inputs: kitten_name (required), args, match.
kitty_last_used_layoutA
Switch to the previously active window layout in the specified tab. Works like a layout toggle between the current and last layout.
Inputs: all, match, no_response.
kitty_launchA
Launch a new process in a kitty window, tab, or OS window. This is the primary window creation tool. Returns the ID of the newly created window. If no command is specified, the default shell is launched. Supports many launch options including window type, location, environment, and stdin source.
Inputs: cwd, env, var, hold, +13 more.
kitty_load_configA
Reload kitty configuration files. If no paths are specified, the previously specified config file is reloaded. Paths are resolved relative to the kitty config directory.
Inputs: paths, override, ignore_overrides.
kitty_lsA
List all kitty OS windows, tabs, and windows as a JSON tree. Returns the full hierarchy: OS-window[] -> tab[] -> window[], including window IDs, titles, PIDs, cwds, foreground processes, and layout info. Use --match / --match-tab to filter. Results are cached for 3 seconds.
Inputs: self, match, match_tab, all_env_vars.
kitty_remove_markerA
Remove the currently set marker (if any) from the specified kitty window.
Inputs: self, match.
kitty_resize_os_windowA
Resize, show, hide, or toggle fullscreen/maximized state of kitty OS windows. Note that some window managers (e.g. tiling WMs) may not allow applications to resize their windows.
Inputs: self, unit, match, width, +3 more.
kitty_resize_windowB
Resize the specified kitty window within its current layout. Not all layouts support resizing in all directions. Use axis "reset" to restore default sizes.
Inputs: axis, self, match, increment.
kitty_runA
Run a program on the computer where kitty is running and get its output (stdout, stderr, exit code). This waits for the process to complete. For fire-and-forget, use kitty_launch with type "background" instead.
Inputs: cmdline (required), env, timeout.
kitty_scrollA
Scroll the content of a kitty window. Supports scrolling by lines, pages, to start/end, to prompts (with shell integration), and unscrolling. Examples: "5" (5 lines down), "2p-" (2 pages up), "start", "end", "1r" (next prompt), "1r-" (previous prompt), "0.5p" (half page down).
Inputs: amount (required), match.
kitty_select_windowA
Visually select a window in a kitty tab. Kitty overlays letter/number labels on each window and waits for user input. Returns the selected window's ID. This is an interactive command with a 60-second timeout.
Inputs: self, match, title, exclude_active, +1 more.
kitty_send_keyA
Send key presses to specified kitty windows. Keys are kitty key names like "ctrl+a", "enter", "shift+f1", "alt+left". All keys are sent as press events then release events in reverse order.
Inputs: keys (required), all, match, match_tab, +1 more.
kitty_send_textA
Send arbitrary text to specified kitty windows. The text follows Python escaping rules on the kitty side (e.g. \e for ESC, \n for newline). Use from_file to send file contents. Use bracketed_paste to control paste mode behavior.
Inputs: all, text, match, from_file, +4 more.
kitty_set_background_opacityA
Set the background opacity for kitty windows. Requires dynamic_background_opacity to be enabled in kitty.conf. Opacity affects all windows in the same OS window.
Inputs: opacity (required), all, match, toggle, +1 more.
kitty_set_colorsA
Set terminal colors for specified windows/tabs. Colors are specified as "key=value" strings (e.g. "foreground=red", "background=#1e1e2e") or a path to a .conf file. Use reset to restore all colors to startup values.
Inputs: all, match, reset, colors, +2 more.
kitty_set_enabled_layoutsA
Set which layouts are available for cycling in the specified tab. If the current layout is not in the list, switches to the first enabled layout. Use "all" or "*" to enable all layouts.
Inputs: layouts (required), match, configured.
kitty_set_font_sizeA
Set the font size in the active OS window. All sub-windows in the same OS window share the same font size. Use "+N"/"-N" for relative changes, a number for absolute size, or "0" to reset to default.
Inputs: size (required), all.
kitty_set_spacingB
Set paddings and margins for specified kitty windows. Settings are "key=value" strings like "margin=20", "padding-left=10", "margin-h=30", "padding-v=5". Use "default" as value to reset.
Inputs: settings (required), all, match, match_tab, +1 more.
kitty_set_tab_colorA
Change the foreground/background colors of a tab in the tab bar. Colors can be color names (e.g. "red"), hex values (e.g. "#1e1e2e"), or "none" to revert to the default.
Inputs: colors (required), self, match.
kitty_set_tab_titleA
Set the title for the specified kitty tabs. If no title is provided, resets to the active-window-controlled title.
Inputs: title (required), match.
kitty_set_user_varsA
Set user variables for the specified kitty windows. User variables are accessible via kitty match expressions (var:NAME). Use "NAME=VALUE" to set, or just "NAME" to unset. If no variables provided, prints current vars.
Inputs: var, self, match.
kitty_set_window_titleA
Set the title for the specified kitty windows. By default the title is permanent (programs cannot change it). Use temporary to allow programs to change it. Omit title to reset to the child-process-controlled title.
Inputs: match, title, temporary.
kitty_signal_childA
Send one or more Unix signals to the foreground process in the specified kitty windows. If no signals are specified, SIGINT is sent by default. Signal names can be with or without the SIG prefix.
Inputs: match, signals.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Each tool targets a distinct action on a specific kitty resource, such as windows, tabs, colors, or markers. Descriptions clearly differentiate between similar operations (e.g., kitty_close_tab vs. kitty_close_window, kitty_get_text vs. kitty_get_tab_text), leaving no ambiguity.
All tools follow a consistent 'kitty_<verb>_<noun>' pattern using lowercase and underscores. Even outliers like kitty_action or kitty_env fit the verb_noun structure. No mixing of conventions or unexpected variations.
With 40 tools, the server exceeds the typical well-scoped range (3-15). While each tool serves a specific purpose, the sheer number may overwhelm agents and suggests excessive granularity, making it harder to navigate.
The tool set covers nearly all aspects of kitty terminal management: window/tab lifecycle, text retrieval, configuration, input, scrolling, layouts, and more. Minor gaps exist (e.g., moving windows between tabs, tab reordering), but core workflows are fully supported.
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA production-grade server for programmatically controlling kitty terminal instances, allowing users to launch windows, send text or key combinations, and capture scrollback buffer content. It facilitates automation workflows and command analysis by providing remote control over the kitty terminal through the Model Context Protocol.4MIT
- AlicenseAqualityBmaintenanceAn MCP server that provides full control over iTerm2 terminal sessions on macOS. It enables users to manage windows, tabs, and panes, run commands, read screen content, and interact with terminal sessions through Claude.18163 PyPI1MIT
- AlicenseAqualityDmaintenanceA lightweight MCP server that enables control of the Tabby terminal via Chrome DevTools Protocol, allowing execution of JavaScript, DOM queries, and screenshots.47MIT
- AlicenseAqualityCmaintenanceMCP server for SSH and local terminal access. Supports interactive commands, long-running processes, and TUI apps like tmux/zellij64MIT