quicker-mcp-server

efds5694/quicker-mcp-server

3.2

If you are the rightful owner of quicker-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Quicker MCP Server enables interaction between Cherry Studio and Quicker automation tools through the Model Context Protocol (MCP).

Quicker MCP Server

一个模型上下文协议（MCP）服务器，使Cherry Studio和其他兼容MCP的AI客户端能够与Quicker自动化工具进行交互。

功能特性

  • 通过ID或名称执行Quicker动作
  • 列出所有可用的Quicker动作并支持过滤
  • 获取和设置剪贴板内容
  • 截图功能
  • 发送键盘输入
  • 获取选中文本
  • 完整的参数传递支持
  • 返回值处理
  • GBK/中文编码支持 - 正确处理中文Windows控制台输出

目录

前置要求

  1. Quicker 必须安装在您的系统上

  2. Python 3.8+ 是必需的（推荐Python 3.12+）

  3. Quicker动作CSV文件（动作列表功能必需）

    • 从Quicker导出您的动作到CSV格式
    • 将CSV文件放在MCP服务器同一目录下
    • 服务器使用绝对路径自动检测CSV文件
    • 默认文件名：QuickerActions_20250719_163336.csv

安装

用户安装

  1. 从PyPI安装（可用时）：

    pip install quicker-mcp-server

  2. 或从源码安装：

    git clone https://github.com/efds5694/quicker-mcp-server.git
cd quicker-mcp-server
pip install .

开发安装

  1. 克隆仓库：

    git clone https://github.com/efds5694/quicker-mcp-server.git
cd quicker-mcp-server

  2. 以开发模式安装并包含开发依赖：

    pip install -e ".[dev]"

  3. 安装pre-commit钩子：

    pre-commit install

快速开始

  1. 安装包：

    pip install quicker-mcp-server

  2. 添加到Cherry Studio：将cherry_studio_config.json中相应的配置复制到您的Cherry Studio MCP设置中。

  3. 开始使用：现在您可以在Cherry Studio中使用自然语言命令来控制Quicker了！

Cherry Studio配置

方法1：使用已安装的包（推荐）

如果您使用pip安装了包：

{
  "mcpServers": {
    "quicker": {
      "command": "quicker-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

方法2：直接使用Python模块

如果您从源码运行：

{
  "mcpServers": {
    "quicker": {
      "command": "python",
      "args": ["-m", "quicker_mcp_server.main"],
      "env": {}
    }
  }
}

方法3：使用uv（如果您使用uv）

{
  "mcpServers": {
    "quicker": {
      "command": "uv",
      "args": ["run", "python", "-m", "quicker_mcp_server.main"],
      "env": {}
    }
  }
}

配置文件

  • cherry_studio_config.json：Cherry Studio的即用配置（推荐方法）
  • cherry_studio_config_examples.json：不同设置的多个配置示例

只需将这些文件中的适当配置复制到您的Cherry Studio MCP设置中。

完整配置参考

以下是 cherry_studio_config.json 的完整内容，包含多种配置选项：

{
  "examples": {
    "installed_package": {
      "description": "Use this if you installed quicker-mcp-server via pip install",
      "config": {
        "mcpServers": {
          "quicker": {
            "command": "quicker-mcp-server",
            "args": [],
            "env": {},
            "description": "Quicke MCP Server - Quicker automation tool MCP server integration"
          }
        }
      }
    },
    "python_module": {
      "description": "Use this if running from source code",
      "config": {
        "mcpServers": {
          "quicker": {
            "command": "python",
            "args": ["-m", "quicker_mcp_server.main"],
            "env": {},
            "description": "Quicke MCP Server - Quicker automation tool MCP server integration"
          }
        }
      }
    },
    "uv_runner": {
      "description": "Use this if you're using uv package manager",
      "config": {
        "mcpServers": {
          "quicker": {
            "command": "uv",
            "args": ["run", "python", "-m", "quicker_mcp_server.main"],
            "env": {},
            "description": "Quicke MCP Server - Quicker automation tool MCP server integration"
          }
        }
      }
    },
    "with_custom_path": {
      "description": "Use this if Quicker is installed in a non-standard location",
      "config": {
        "mcpServers": {
          "quicker": {
            "command": "quicker-mcp-server",
            "args": [],
            "env": {
              "QUICKER_PATH": "C:\\Custom\\Path\\To\\Quicker\\QuickerStarter.exe"
            },
            "description": "Quicke MCP Server - Quicker automation tool MCP server integration"
          }
        }
      }
    }
  },
  "recommended": {
    "mcpServers": {
      "quicker": {
        "command": "quicker-mcp-server",
        "args": [],
        "env": {},
        "description": "Quicke MCP Server - Quicker automation tool MCP server integration"
      }
    }
  }
}
配置选择指南
  1. 推荐配置 (recommended)：适用于大多数用户，使用pip安装的包
  2. 已安装包 (installed_package)：与推荐配置相同，适用于通过pip安装的情况
  3. Python模块 (python_module)：适用于从源码运行的开发环境
  4. uv运行器 (uv_runner)：适用于使用uv包管理器的用户
  5. 自定义路径 (with_custom_path)：适用于Quicker安装在非标准位置的情况

必需的Quicker动作

您需要在Quicker中创建几个基本动作，以便MCP服务器正常工作。

必需的动作包括：

  • get_clipboard_content - 获取当前剪贴板文本
  • set_clipboard_content - 设置剪贴板内容
  • take_screenshot - 截图并保存
  • send_keys - 发送键盘输入
  • get_selected_text - 获取当前选中的文本

Quicker动作设置指南

为了让MCP Server正常工作，您需要在Quicker中创建以下基础动作。每个动作都需要设置正确的名称，以便MCP Server能够调用。

1. get_clipboard_content（获取剪贴板内容）

动作名称：get_clipboard_content

步骤：

  1. 添加"获取剪贴板文本"模块
  2. 添加"停止"模块，将剪贴板文本作为返回值

具体配置：

  • 获取剪贴板文本 → 输出到变量 clipboardText
  • 停止 → 返回内容：{clipboardText}

2. set_clipboard_content（设置剪贴板内容）

动作名称：set_clipboard_content

详细创建步骤：

  1. 右键点击Quicker面板空白处，选择"新建动作"
  2. 设置动作名称为：set_clipboard_content
  3. 在动作编辑器中：
    • 拖入"写入剪贴板"模块
    • 点击"内容"参数框
    • 输入：{_in_param}（注意大括号和下划线）
    • 或者点击参数框右边的fx按钮，在表达式中输入：_in_param
  4. 拖入"停止"模块
    • 在"返回内容"中输入："Clipboard content set successfully"
  5. 保存动作

参数说明：

  • _in_param 是Quicker的内置变量，无需手动定义
  • 当通过命令行调用时：runaction:set_clipboard_content?Hello World
  • "Hello World" 会自动存储在 _in_param 变量中
  • 使用 {_in_param} 进行文本插值来获取参数值

3. take_screenshot（截图）

动作名称：take_screenshot

步骤：

  1. 添加"屏幕截图"模块
  2. 根据参数决定保存路径
  3. 返回截图文件路径

具体配置：

  • 如果/否则 → 条件：{_in_param} 不为空
    • 是：屏幕截图 → 保存到：{_in_param}
    • 否：屏幕截图 → 保存到：{GetFolderPath("Desktop")}\screenshot_{GetTime("yyyyMMdd_HHmmss")}.png
  • 停止 → 返回内容：截图文件的完整路径

4. send_keys（发送按键）

动作名称：send_keys

详细创建步骤：

  1. 新建动作，名称设为：send_keys
  2. 拖入"模拟按键B（参数）"模块
    • 在"按键内容"参数中输入：{_in_param}
  3. 拖入"停止"模块
    • 在"返回内容"中输入："Keys sent: {_in_param}"

使用示例：

  • 调用：runaction:send_keys?Ctrl+C → 执行复制操作
  • 调用：runaction:send_keys?Hello World → 输入文本
  • 调用：runaction:send_keys?{Win}+R → 打开运行对话框

5. get_selected_text（获取选中文本）

动作名称：get_selected_text

具体配置：

  • 获取选中的文本 → 输出到变量 selectedText
  • 停止 → 返回内容：{selectedText}

创建步骤总结

  1. 打开Quicker软件
  2. 在面板上右键点击空白位置，选择"新建动作"
  3. 设置动作名称（必须与上面列出的名称完全一致）
  4. 按照上述配置添加相应的模块
  5. 保存动作

高级配置

参数处理
  • 使用 {_in_param} 来获取从MCP Server传递的参数
  • 如果需要处理多个参数，可以使用分隔符（如|）分割参数字符串
错误处理

建议在每个动作中添加错误处理：

尝试
  [主要逻辑]
捕获异常
  停止 → 返回内容："Error: {异常信息}"
返回值格式
  • 简单文本：直接返回字符串
  • JSON格式：返回结构化数据
  • 文件路径：返回完整的文件路径

测试动作

创建完成后，可以通过以下方式测试：

  1. 命令行测试：

    "C:\Program Files\Quicker\QuickerStarter.exe" -c "runaction:get_clipboard_content"

  2. 在Quicker中直接运行：

    • 右键点击动作
    • 选择"运行"或"调试运行"

扩展动作

您可以根据需要创建更多自定义动作，例如：

  • 文件操作（复制、移动、删除）
  • 窗口管理（最大化、最小化、切换）
  • 系统信息获取
  • 网络请求
  • 数据库操作

只需要确保动作名称在MCP Server中有对应的调用即可。

使用示例

在Cherry Studio中配置完成后，您可以使用自然语言来控制Quicker：

  • "截图并保存到我的桌面"
  • "复制选中的文本到剪贴板"
  • "按Ctrl+C进行复制"
  • "获取当前剪贴板内容"
  • "运行我的自定义Quicker动作'ProcessFiles'"
  • "显示所有可用的Quicker动作"
  • "列出与Excel相关的动作"
  • "查找包含'截图'的动作"

高级用法

自定义动作执行

您可以通过ID或名称执行任何Quicker动作：

运行ID为"25d718df-0f37-43ae-9fac-58fca1888113"的Quicker动作，参数为"hello world"
  • "执行ID为70f76130-10e5-4c22-a17b-e3bd2338b5a2的动作"

动作参数

使用parameters字段向Quicker动作传递参数。参数将通过标准参数机制在Quicker动作中可用。

列出可用动作

MCP服务器可以从CSV导出文件中读取并显示您的所有Quicker动作：

"显示所有可用的Quicker动作"
"列出前20个动作"
"查找包含'Excel'的动作"
"显示与截图相关的动作"

服务器将显示：

  • 动作ID（用于精确执行）
  • 动作名称（人类可读）
  • 描述
  • 动作类型（SendKeys、XAction、RunProgram等）
  • 关联应用程序
  • 上下文/配置文件信息

故障排除

  1. 找不到Quicker：如果Quicker安装在不同位置，请更新脚本中的quicker_path

  2. 找不到动作：确保动作ID/名称在您的Quicker安装中存在

  3. 权限问题：确保Quicker具有执行系统操作的必要权限

  4. 超时问题：为长时间运行的动作增加超时值

  5. 中文字符编码问题：服务器自动处理中文Windows中常见的GBK/GB2312编码。如果仍然看到编码问题，请检查系统区域设置。

  6. 测试编码：使用test_gbk_fix.py测试编码处理是否与您的Quicker设置正确配合

项目结构

quicker-mcp-server/
├── src/quicker_mcp_server/           # 源代码
│   ├── __init__.py                  # 包初始化
│   ├── main.py                      # 入口点
│   ├── server.py                    # MCP服务器实现
│   └── resources.py                 # 资源管理模块
├── data/                            # 用户数据目录（不打包）
│   ├── QuickerActions_*.csv         # 用户的动作文件
│   ├── mcp_config.json              # MCP配置文件（未来添加）
│   ├── configs/                     # 其他配置文件
│   │   └── cherry_studio_config.json
│   └── logs/                        # 日志文件
│       └── quicker_mcp_server.log
├── docs/                            # 文档资源
│   ├── images/                      # 文档图片
│   ├── examples/                    # 示例文件
│   └── quicker_doc/                 # Quicker动作编写和使用的说明文档
│       ├── basic.txt
│       ├── clipboard-related.txt
│       ├── flow-control.txt
│       └── ... (所有Quicker相关文档)
├── tests/                           # 测试文件
│   ├── fixtures/                    # 测试数据
│   │   └── sample_actions.csv
│   ├── __init__.py
│   ├── conftest.py                  # Pytest配置
│   ├── test_main.py                 # 主模块测试
│   └── test_server.py               # 服务器测试
├── scripts/                         # 工具脚本
│   └── setup_config.py
├── .github/workflows/               # GitHub Actions CI/CD
│   ├── ci.yml                       # 持续集成
│   └── release.yml                  # 发布自动化
├── pyproject.toml                   # 项目配置
├── .pre-commit-config.yaml          # Pre-commit钩子
├── .flake8                          # Flake8配置
├── .gitignore                       # Git忽略规则
├── cherry_studio_config.json        # Cherry Studio MCP配置
├── cherry_studio_config_examples.json  # 配置示例
├── dev.bat                          # Windows开发辅助脚本
├── Makefile                         # Unix开发辅助
├── LICENSE                          # MIT许可证
└── README.md                        # 本文件

开发

开发工作流程

  1. 设置开发环境：

    git clone https://github.com/efds5694/quicker-mcp-server.git
cd quicker-mcp-server
pip install -e ".[dev]"
pre-commit install

  2. 代码质量工具：

    • Black：代码格式化
    • isort：导入排序
    • flake8：代码检查
    • mypy：类型检查
    • pytest：测试

  3. 运行测试：

    # 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=quicker_mcp_server

# 运行特定测试文件
pytest tests/test_server.py

  4. 代码格式化：

    # 格式化代码
black src/ tests/

# 排序导入
isort src/ tests/

# 检查代码规范
flake8 src/ tests/

# 类型检查
mypy src/

  5. Pre-commit钩子： Pre-commit钩子在每次提交时自动运行以确保代码质量。

    # 手动运行
pre-commit run --all-files

添加新功能

要扩展此MCP服务器：

  1. 添加新工具：在src/quicker_mcp_server/server.py的setup_tools()方法中
  2. 实现相应的处理方法：在同一文件中
  3. 创建匹配的Quicker动作：如果需要
  4. 为新功能编写测试：在tests/目录中
  5. 更新文档：在README.md中

测试

项目使用pytest进行测试，结构如下：

  • tests/conftest.py：共享的fixtures和配置
  • tests/test_*.py：每个组件的测试模块
  • 默认启用覆盖率报告

贡献

  1. Fork仓库
  2. 创建功能分支：git checkout -b feature-name
  3. 按照开发工作流程进行更改
  4. 确保所有测试通过且代码质量检查通过
  5. 提交更改：git commit -am 'Add feature'
  6. 推送到分支：git push origin feature-name
  7. 创建Pull Request

许可证

MIT许可证 - 详见LICENSE文件