ghostty-mcp

Ghostty MCP Server

A Model Context Protocol (MCP) server for Ghostty, the fast, native, feature-rich terminal emulator. This server enables AI assistants like Claude to interact with and control Ghostty through a standardized interface.

Features

• Configuration Management: Get and set Ghostty configuration values
• Theme Control: Switch between themes and manage light/dark modes
• Keybinding Management: Add, modify, or remove custom keybindings
• Command Execution: Run commands directly in Ghostty
• Window Management: Create, split, and manage Ghostty windows
• Live Reload: Reload configuration without restarting
• Discovery: List available themes, keybindings, and configurations

Installation

1. Clone this repository:

git clone https://github.com/yourusername/ghostty-mcp.git
cd ghostty-mcp

1. Install dependencies:

npm install

1. Build the project:

npm run build

Configuration

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ghostty": {
      "command": "node",
      "args": ["/path/to/ghostty-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Replace /path/to/ghostty-mcp with the actual path to your cloned repository.

Available Tools

ghostty_config

Get or set Ghostty configuration values.

Parameters:

• key (string, required): Configuration key (e.g., "font-size", "theme", "window-decoration")
• value (string, optional): Configuration value. If not provided, returns current value

Examples: ``` // Get current font size ghostty_config(key: "font-size")

// Set font size to 14 ghostty_config(key: "font-size", value: "14") ```

ghostty_theme

Change Ghostty theme.

Parameters:

• theme (string, required): Theme name to apply
• mode (string, optional): Theme mode - "light", "dark", or "auto"

Examples: ``` // Apply dracula theme ghostty_theme(theme: "dracula")

// Set github_light for light mode ghostty_theme(theme: "github_light", mode: "light") ```

ghostty_keybind

Manage Ghostty keybindings.

Parameters:

• action (string, required): Action to bind (e.g., "copy", "paste", "new_tab")
• key (string, required): Key combination (e.g., "cmd+c", "ctrl+shift+t")
• remove (boolean, optional): If true, removes the keybinding

Examples: ``` // Add keybinding for new tab ghostty_keybind(action: "new_tab", key: "cmd+t")

// Remove keybinding ghostty_keybind(action: "new_tab", remove: true) ```

ghostty_command

Execute commands in Ghostty.

Parameters:

• command (string, required): Command to execute
• wait (boolean, optional): Whether to wait for command completion

Examples: ``` // Run a command ghostty_command(command: "ls -la")

// Run and wait for completion ghostty_command(command: "npm install", wait: true) ```

ghostty_window

Manage Ghostty windows and splits.

Parameters:

• action (string, required): One of:
• "new": Create new window
• "close": Close current window
• "split-horizontal": Split horizontally
• "split-vertical": Split vertically
• "focus-next": Focus next pane
• "focus-previous": Focus previous pane
• config (object, optional): Additional window configuration

Examples: ``` // Create new window ghostty_window(action: "new")

// Split vertically ghostty_window(action: "split-vertical") ```

ghostty_reload

Reload Ghostty configuration.

Parameters:

• scope (string, optional): What to reload - "config", "theme", or "all" (default: "all")

Examples: ``` // Reload all configuration ghostty_reload()

// Reload only theme ghostty_reload(scope: "theme") ```

ghostty_list

List available themes, keybindings, or configuration.

Parameters:

• type (string, required): What to list - "themes", "keybindings", or "config"
• filter (string, optional): Optional filter for results

Examples: ``` // List all themes ghostty_list(type: "themes")

// List keybindings containing "tab" ghostty_list(type: "keybindings", filter: "tab") ```

Development

Running in Development Mode

npm run dev

Building

npm run build

Testing with MCP Inspector

You can test this server using the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Requirements

• Node.js 18 or later
• Ghostty terminal emulator installed
• Access to Ghostty CLI commands

Platform Support

This MCP server supports:

• macOS
• Linux
• Windows (with appropriate path adjustments)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

• Ghostty by Mitchell Hashimoto
• Model Context Protocol by Anthropic