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

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