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+

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