Keyboard Shortcuts MCP Server

A Model Context Protocol (MCP) server that provides keyboard shortcuts for various operating systems, desktop environments, and applications. Uses Claude Opus for intelligent natural language querying of shortcuts.

Primary Use Case: Designed to support Claude's Computer Use tool by providing accurate, context-aware keyboard shortcuts for automated computer interactions.

Features

• 🔍 Intelligent Search: Uses Claude Opus to understand natural language queries
• 🖥️ Multi-Platform: Support for Ubuntu (GNOME desktop), with architecture for macOS/Windows
• 📱 App-Specific: Desktop apps (Firefox, VS Code), CLI tools (tmux, vim), and system shortcuts
• 🚀 Fast: All shortcut data loaded in-memory for quick filtering

Installation

# Install dependencies
pnpm install

# Build the server
pnpm build

Configuration

Set your Anthropic API key as an environment variable:

export ANTHROPIC_API_KEY="your-api-key-here"

Usage

Running Standalone

pnpm start

Integrating with Claude Desktop

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "keyboard-shortcuts": {
      "command": "node",
      "args": ["/path/to/keyboard-shortcuts-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tool: get_shortcuts

Query keyboard shortcuts using natural language.

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

Shortcuts are organized as:

data/
└── ubuntu/
    ├── desktops/
    │   └── gnome/
    │       ├── window-management.json
    │       ├── system-functions.json
    │       └── ...
    ├── apps/
    │   ├── browser/
    │   │   ├── firefox.json
    │   │   └── chrome.json
    │   ├── editor/
    │   │   ├── vscode.json
    │   │   └── vim.json
    │   └── ...
    └── tools/
        ├── tmux.json
        ├── vim.json
        └── ...

Each JSON file contains:

{
  "os": "ubuntu",
  "desktop": "gnome" | null,
  "application": "firefox" | null,
  "file": "firefox",
  "categories": [
    {
      "name": "Tab Management",
      "shortcuts": [
        {
          "keys": "Ctrl + T",
          "description": "New tab"
        }
      ]
    }
  ]
}

Development

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

# Build TypeScript
pnpm build

# Run built server
pnpm start

Architecture

1. Data Loader (src/data-loader.ts): Loads all JSON files at startup into memory
2. Opus Client (src/opus-client.ts): Wraps Anthropic SDK for intelligent queries
3. MCP Server (src/index.ts): Exposes get_shortcuts tool via MCP protocol

The server filters shortcuts by OS/desktop/app, then passes relevant data + user query to Claude Opus for intelligent matching.

License

MIT