Keyboard Shortcuts MCP Server

# 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](https://docs.claude.com/en/docs/agents-and-tools/tool-use/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 ```bash # Install dependencies pnpm install # Build the server pnpm build ``` ## Configuration Set your Anthropic API key as an environment variable: ```bash export ANTHROPIC_API_KEY="your-api-key-here" ``` ## Usage ### Running Standalone ```bash pnpm start ``` ### Integrating with Claude Desktop Add to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "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 ```typescript // 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: ```json { "os": "ubuntu", "desktop": "gnome" | null, "application": "firefox" | null, "file": "firefox", "categories": [ { "name": "Tab Management", "shortcuts": [ { "keys": "Ctrl + T", "description": "New tab" } ] } ] } ``` ## Development ```bash # 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