Keyboard Shortcuts

You are using a specialized MCP server that provides keyboard shortcuts for operating systems, desktops, and applications. It loads all shortcut data into memory for fast queries and uses Claude Opus to understand natural language questions, so you can quickly discover the right shortcut in context.

How to use

You interact with the Keyboard Shortcuts MCP Server through an MCP client. Start by running the server locally, then connect your client by pointing it to the local MCP process. Ask natural language questions like, “how do I split a tmux pane” or “what shortcuts open a new private window in Firefox on GNOME” and you will receive accurate, context-aware shortcuts filtered for your OS, desktop, and application.

How to install

# Install dependencies
pnpm install

# Build the server
pnpm build

# Run the built server locally (as a start example)
pnpm start

Prerequisites you need before installing:

• Node.js and pnpm installed on your system
• A supported operating system (Ubuntu with GNOME desktop is shown as the primary example)
• Access to an Anthropic API key if you plan to use Claude Opus for intelligent querying If you plan to integrate with Claude Desktop, you will provide a local MCP command that runs the built server and passes your API key as an environment variable.

Configuration and usage notes

# Example: Claude Desktop integration config (macOS)
{
  "mcpServers": {
    "keyboard-shortcuts": {
      "command": "node",
      "args": ["/path/to/keyboard-shortcuts-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Set your Anthropic API key in your environment when running or configuring the client to enable natural language querying. You can run the server locally with the in-tree build output and connect your MCP client to this local process.

## Tool: get\_shortcuts

The server exposes a tool named `get_shortcuts` that lets you query keyboard shortcuts using natural language. You provide the operating system, optional desktop environment, optional application, and your query, and you receive matching shortcuts.

Parameters
- `os` (required): Operating system - `ubuntu`, `macos`, or `windows`
- `query` (required): Natural language question about shortcuts
- `desktop` (optional): Desktop environment - `gnome`, `kde`, etc.
- `application` (optional): Specific application - `firefox`, `tmux`, etc.

Examples

// Query tmux shortcuts (no desktop needed for CLI tools)
{
  "os": "ubuntu",
  "application": "tmux",
  "query": "how do I split a pane vertically?"
}

// Query Firefox shortcuts on GNOME
{
  "os": "ubuntu",
  "desktop": "gnome",
  "application": "firefox",
  "query": "how to open a new private window"
}

// Query GNOME window management
{
  "os": "ubuntu",
  "desktop": "gnome",
  "query": "tile window to left half of screen"
}

Data structure overview

Shortcuts are organized in a data tree under data/ubuntu, with optional desktops, apps, and tools categories. Each file describes an OS, optional desktop, and optional app, and includes categorized shortcuts with keys and descriptions.

Development

# Watch mode (auto-reload on changes)
pnpm dev

# Build TypeScript
pnpm build

# Run built server
pnpm start

Architecture

The server initializes by loading all shortcut data into memory, then uses Claude Opus to perform intelligent matching against your query. It exposes a single MCP tool get_shortcuts to query the data and filter results by OS, desktop, and application.

Security considerations

Protect your API keys and credentials. Do not expose your Anthropic API key in publicly accessible configurations. Restrict access to the running MCP server and use environment variables to supply sensitive keys only to trusted clients.

Troubleshooting

If you cannot obtain results, verify:

• The server is running and reachable by your MCP client
• The Anthropic API key is correctly set in the environment
• Your query includes the appropriate OS, desktop (if needed), and application information so filtering can occur.

Available tools

get_shortcuts

Query keyboard shortcuts using natural language for a given OS, desktop, and application.