Kitty MCP Server

Kitty MCP Server

A production-grade MCP server for controlling kitty terminal instances

A production-grade Model Context Protocol (MCP) server for controlling kitty terminal instances.

Overview

• Create, manage, and control kitty terminal instances programmatically
• Send text and key combinations to kitty windows
• Capture scrollback buffer content for command output analysis
• Useful for long running processes, analyzing logs, and automation workflows
• All instances launched with --app-id for window identification

Features

• Launch kitty instances with unique Unix sockets and app-id
• Send text and key combinations to windows
• Launch windows within existing instances
• Capture scrollback buffer content
• Manage app-ids for window identification
• List and close instances
• JSON structured logging
• Async/await throughout
• Comprehensive error handling

Installation

Prerequisites

• Python 3.11+
• kitty terminal installed and in PATH
• uv (recommended) or pip

Install from PyPI

# Install from PyPI
pip install kitty-mcp

# Install with uv (recommended)
uv add kitty-mcp

Install from Source

# Clone repository
git clone https://github.com/your-username/kitty-mcp.git
cd kitty-mcp

# Install with uv
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

Usage

Running the Server

# Run directly
python -m kitty_mcp

# Or using the installed script
kitty-mcp

The server communicates via stdio (standard input/output) for MCP compatibility.

Configuration

Create a configuration file at ~/.config/kitty-mcp/config.json:

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

Configuration options:

• socket_dir: Directory for Unix sockets (default: /tmp/kitty-mcp-<uid>)
• max_instances: Maximum concurrent instances (default: 10, max: 100)
• socket_permissions: Socket file permissions (default: "0600")
• logging.level: Log level (DEBUG, INFO, WARNING, ERROR)
• kitty.launch_timeout: Timeout for launching kitty (seconds)
• kitty.command_timeout: Timeout for RC commands (seconds)

Available Tools

launch

Launch a new kitty instance with remote control enabled.

Parameters:

• app_id (string, required): Unique identifier for the instance
• working_directory (string, optional): Working directory
• window_class (string, optional): Window class (defaults to app_id)

Returns: {"success": true, "app_id": "...", "socket_path": "...", "pid": 1234}

send_text

Send text to a kitty window.

Parameters:

• app_id (string, required): Instance identifier
• text (string, required): Text to send
• match (string, optional): Window matching criteria

send_key

Send key combination to a kitty window.

Parameters:

• app_id (string, required): Instance identifier
• key (string, required): Key combination (e.g., "ctrl+c", "enter")
• match (string, optional): Window matching criteria

launch_window

Launch a new window in an existing kitty instance.

Parameters:

• app_id (string, required): Instance identifier
• command (array, required): Command to run
• cwd (string, optional): Working directory

get_scrollback

Capture scrollback buffer content.

Parameters:

• app_id (string, required): Instance identifier
• lines (integer, optional): Number of lines (default: all)
• match (string, optional): Window matching criteria

Returns: {"success": true, "content": "..."}

close

Close a kitty instance.

Parameters:

• app_id (string, required): Instance identifier
• force (boolean, optional): Force close

get_app_id

Get the app-id of a running kitty instance.

Parameters:

• app_id (s