Skip to main content
Glama
kitty-mcp-server
by secemp9

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 build

kitty.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

KITTY_MCP_SOCKET

Override the kitty remote control socket path. Takes highest priority.

KITTY_LISTEN_ON

Set automatically by kitty inside its windows. Used as fallback when KITTY_MCP_SOCKET is not set.

KITTY_MCP_BINARY

Override the kitty CLI binary name or path. Default: kitten.

KITTY_RC_PASSWORD

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 tree

  • kitty_get_text -- retrieve text content from a window (screen, scrollback, selection, last command output)

  • kitty_get_colors -- get terminal color definitions

  • kitty_select_window -- visually select a window with overlay labels

Window Management

  • kitty_launch -- launch a new process in a window, tab, or OS window

  • kitty_close_window -- close windows

  • kitty_focus_window -- focus a window

  • kitty_resize_window -- resize a window within its layout

  • kitty_detach_window -- move windows to a different tab or OS window

  • kitty_set_window_title -- set window title

Tab Management

  • kitty_close_tab -- close tabs

  • kitty_focus_tab -- focus a tab

  • kitty_set_tab_title -- set tab title

  • kitty_set_tab_color -- change tab bar colors

  • kitty_detach_tab -- move tabs to a different OS window

Text / Input

  • kitty_send_text -- send text to windows

  • kitty_send_key -- send key presses to windows

Scroll

  • kitty_scroll -- scroll window content (lines, pages, prompts, start/end)

Appearance

  • kitty_set_colors -- set terminal colors

  • kitty_set_font_size -- set font size

  • kitty_set_spacing -- set padding and margins

  • kitty_set_background_opacity -- set background opacity

  • kitty_disable_ligatures -- control ligature rendering

Layout

  • kitty_goto_layout -- switch to a specific layout

  • kitty_last_used_layout -- toggle to the previous layout

  • kitty_set_enabled_layouts -- set which layouts are available for cycling

Markers

  • kitty_create_marker -- highlight text matching a pattern

  • kitty_remove_marker -- remove markers from a window

System

  • kitty_run -- run a program and get its output

  • kitty_action -- run a mappable kitty action

  • kitty_kitten -- run a kitten (kitty extension)

  • kitty_load_config -- reload kitty configuration

  • kitty_signal_child -- send Unix signals to foreground processes

  • kitty_env -- change environment variables for new windows

  • kitty_set_user_vars -- set user variables on windows

  • kitty_resize_os_window -- resize, fullscreen, or hide OS windows

Composite (multi-step operations)

  • kitty_dump_scrollback -- dump scrollback to a temp file with pagination

  • kitty_get_tab_text -- get text from all windows in a tab in one call

Utility

  • kitty_clear_cache -- clear the MCP server internal cache

  • kitty_health_check -- verify kitty connectivity and server status

License

MIT

Available Tools

40 tools
kitty_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

    A3.8/5.0

    Scored across 40 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      18
      163 PyPI
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for SSH and local terminal access. Supports interactive commands, long-running processes, and TUI apps like tmux/zellij
      6
      4
      MIT