# 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](https://modelcontextprotocol.io). Communicates with kitty through its remote control protocol using the `kitten` CLI.

## Prerequisites

- [kitty](https://sw.kovidgoyal.net/kitty/) terminal emulator with remote control enabled
- Node.js 20+

## Installation

```bash
npm install
npm run build
```

## kitty.conf setup

Add these lines to your `~/.config/kitty/kitty.conf`:

```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`:

```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

```json
{
  "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