Kitty

Provides programmatic control over kitty terminal instances, including launching, input, window management, and scrollback capture via an MCP server.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "den-tanui-kitty-mcp": {
      "command": "python",
      "args": [
        "-m",
        "kitty_mcp"
      ]
    }
  }
}

You are using a production-grade MCP server that lets you control kitty terminal instances programmatically. With this server, you can create, manage, and interact with kitty windows, send text and key combinations, capture output from the scrollback, and organize windows using app-ids for precise targeting. This enables automation, long-running processes, and streamlined workflows where terminal control is essential.

How to use

You will run the MCP server as a local process and connect to it from an MCP client via standard input/output. The server exposes a set of operations to launch kitty instances, send input, launch additional windows, capture output, manage app-ids, list active instances, and close or reconfigure running sessions. Each operation targets a specific instance by its app-id, allowing you to automate complex workflows across multiple terminals.

How to install

Prerequisites you need before starting:

Python 3.11+
kitty
uv
pip

Install the MCP server package from PyPI or install from source using the provided commands.

Configuration and startup

The server runs via stdio, so you start it as a local process. You can run it directly with Python or use the installed script if available.

# Run directly using Python
python -m kitty_mcp

# Or use the installed script
kitty-mcp

Configuration file

Create a configuration file at your home directory to customize sockets, limits, and logging. The example below shows common options you may adjust.

{
  "socket_dir": "/tmp/kitty-mcp",
  "max_instances": 10,
  "socket_permissions": "0600",
  "logging": {
    "level": "INFO"
  },
  "kitty": {
    "launch_timeout": 30,
    "command_timeout": 30
  }
}

Available capabilities (tools)

You can perform a range of actions to manage kitty instances. The following tools are available for use with your MCP client.

launch: Create a new kitty instance with remote control enabled and a unique app-id.
send_text: Send text to a specific kitty window.
send_key: Send a key combination to a window.
launch_window: Start a new window inside an existing instance.
get_scrollback: Retrieve the scrollback content for analysis.
close: Close a kitty instance, with an option to force close.
get_app_id: Retrieve the configured app-id for an instance.
set_app_id: Update the app-id tracking for an instance.
list_instances: List all active managed kitty instances.

Available tools

launch

Launch a new kitty instance with remote control enabled and assign a unique app-id to identify the instance.

send_text

Send arbitrary text to a specific kitty window or set of windows matched by criteria.

send_key

Send a keyboard shortcut or key sequence to a kitty window.

launch_window

Launch a new window inside an existing kitty instance for running commands.

get_scrollback

Capture and return the scrollback content for analysis or logging.

close

Close a kitty instance, with an option to force termination.

get_app_id

Retrieve the currently configured app-id for a running instance.

set_app_id

Update the app-id tracking for an existing instance.

list_instances

List all active kitty instances managed by the MCP server.