Ghostty

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

2. Install dependencies:

npm install

3. 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