yo-execute-shortcuts-mcp

一个基于 MCP (Model Context Protocol) 的全局快捷键执行工具，允许大模型通过 MCP 协议调用系统全局快捷键。

功能特性

• 🎹 支持全局快捷键执行
• 🔌 基于 MCP 协议，可与 Cursor、Claude Desktop 等工具集成
• ⚙️ 灵活的配置方式，支持通过命令行参数或环境变量传入配置
• 🚀 支持通过 npx 直接执行
• 📦 使用 TypeScript 编写，类型安全

安装

npm install -g yo-execute-shortcuts-mcp
# 或
pnpm add -g yo-execute-shortcuts-mcp

使用方法

1. 通过 npx 直接执行

npx yo-execute-shortcuts-mcp --config '[{"name":"汽水音乐","description":"用于汽水音乐APP控制","shortcuts":[{"name":"播放","command":"command+option+p"}]}]'

2. 通过环境变量配置

export SHORTCUTS_CONFIG='[{"name":"汽水音乐","description":"用于汽水音乐APP控制","shortcuts":[{"name":"播放","command":"command+option+p"}]}]'
npx yo-execute-shortcuts-mcp

3. 使用配置文件

创建一个 JSON 配置文件（例如 config.json），然后：

npx yo-execute-shortcuts-mcp --config config.json

4. 在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加（macOS: ~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json 或 Windows: %APPDATA%\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json）：

方式一：使用 JSON 字符串（适合简单配置）

{
  "mcpServers": {
    "yo-execute-shortcuts-mcp": {
      "command": "npx",
      "args": [
        "yo-execute-shortcuts-mcp",
        "--config",
        "[{\"name\":\"汽水音乐\",\"description\":\"用于汽水音乐APP控制，切换歌曲 调整音量等\",\"shortcuts\":[{\"name\":\"播放\",\"command\":\"command+option+p\"},{\"name\":\"暂停\",\"command\":\"command+option+p\"},{\"name\":\"下一首\",\"command\":\"command+option+right\"},{\"name\":\"上一首\",\"command\":\"command+option+left\"}]},{\"name\":\"网易云音乐\",\"description\":\"用于网易云音乐APP控制，切换歌曲 调整音量等\",\"shortcuts\":[{\"name\":\"播放\",\"command\":\"command+option+p\"}]}]"
      ]
    }
  }
}

方式二：使用配置文件（推荐，更易维护）

{
  "mcpServers": {
    "yo-execute-shortcuts-mcp": {
      "command": "npx",
      "args": [
        "yo-execute-shortcuts-mcp",
        "--config",
        "/path/to/your/config.json"
      ]
    }
  }
}

配置格式

配置是一个 JSON 数组，每个元素代表一个应用：

[
  {
    "name": "应用名称",
    "description": "应用描述",
    "shortcuts": [
      {
        "name": "快捷键名称",
        "command": "快捷键命令"
      }
    ]
  }
]

快捷键命令格式

快捷键命令使用 + 分隔修饰键和主键，例如：

• command+option+p - Command + Option + P
• control+shift+c - Control + Shift + C
• command+space - Command + Space

支持的修饰键：

• command / cmd / meta - Command 键 (macOS) 或 Windows 键
• control / ctrl - Control 键
• option / alt - Option/Alt 键
• shift - Shift 键

支持的主键：

• 字母键: a-z
• 数字键: 0-9
• 功能键: f1-f12
• 方向键: up, down, left, right
• 特殊键: space, enter, escape, tab, backspace, delete, home, end, pageup, pagedown

MCP 工具

服务器会为每个配置的快捷键自动创建对应的 MCP 工具：

1. 特定工具: execute_shortcut_{应用名}_{快捷键名}

   • 直接执行特定应用的特定快捷键
   • 无需参数

2. 通用工具: execute_shortcut

   • 通过参数执行快捷键
   • 参数：
     • app (string): 应用名称
     • shortcut (string): 快捷键名称
     • command (string): 直接指定快捷键命令（优先级最高）

示例配置

[
  {
    "name": "汽水音乐",
    "description": "用于汽水音乐APP控制，切换歌曲 调整音量等",
    "shortcuts": [
      {
        "name": "播放",
        "command": "command+option+p"
      },
      {
        "name": "暂停",
        "command": "command+option+p"
      },
      {
        "name": "下一首",
        "command": "command+option+right"
      },
      {
        "name": "上一首",
        "command": "command+option+left"
      }
    ]
  },
  {
    "name": "网易云音乐",
    "description": "用于网易云音乐APP控制，切换歌曲 调整音量等",
    "shortcuts": [
      {
        "name": "播放",
        "command": "command+option+p"
      }
    ]
  }
]

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 开发模式（监听文件变化）
pnpm dev

可以通过以下方式使用：

npx yo-execute-shortcuts-mcp --config '[{"name":"应用名",...}]'

日志系统

所有日志输出到 stderr，不会干扰 MCP 协议的 stdout 通信。

日志级别

通过环境变量 LOG_LEVEL 控制日志级别：

• DEBUG - 输出所有日志，包括调试信息
• INFO - 输出信息、警告和错误日志（默认）
• WARN - 只输出警告和错误日志
• ERROR - 只输出错误日志
• SILENT - 不输出任何日志

使用示例

# 启用调试日志
LOG_LEVEL=DEBUG npx yo-execute-shortcuts-mcp --config '[...]'

# 只输出错误日志
LOG_LEVEL=ERROR npx yo-execute-shortcuts-mcp --config '[...]'

日志格式

日志格式：[时间戳] [级别] 消息 [附加数据]

示例：

[2024-01-01T12:00:00.000Z] [INFO] yo-execute-shortcuts-mcp 服务器已启动
[2024-01-01T12:00:00.100Z] [DEBUG] 执行快捷键 { "shortcut": "command+option+p" }

注意事项

1. 全局快捷键需要系统权限，首次使用时可能需要授权
2. macOS 用户可能需要在"系统设置 > 隐私与安全性 > 辅助功能"中授予终端权限
3. Windows 用户可能需要以管理员权限运行
4. 快捷键命令区分大小写，但解析时会自动转换为小写
5. 所有日志输出到 stderr，确保不会干扰 MCP 协议的通信

许可证

ISC