BetterTouchTool MCP服务器
A. 模型上下文协议（MCP） 服务器，使克劳德等人工智能助手能够控制和交互 BetterTouch工具 在macOS上。
这是什么？
此MCP服务器充当Claude（或其他兼容MCP的AI助手）和BetterTouchTool之间的桥梁，允许您：
- 查询您的BTT配置 -了解您设置了哪些触发器、快捷方式和自动化
- 执行触发器和操作 -运行命名触发器、键盘快捷键或任何BTT操作
- 管理变量 -获取和设置动态工作流的BTT变量
- 更新小部件 -实时修改触摸栏、菜单栏或Stream Deck小部件
- 控制预设 -导出、导入和管理BTT预设
- 访问剪贴板 -以编程方式读取和写入剪贴板内容
先决条件
- macOS （BetterTouchTool仅适用于macOS）
- BetterTouch工具 使用有效许可证安装
- Python 3.12+
- 紫外线 （推荐）或pip用于包管理
- 克劳德桌面版 或另一个MCP兼容客户端
安装
1.启用BTT Web服务器
首先，启用BetterTouchTool Web服务器：
- 打开BetterTouchTool
- 首选 偏好 → 高级 → Web服务器
- 检查 启用Web服务器
- 注意端口（默认值：
56786) - 可选择设置a 共享的秘密 用于身份验证
2.安装MCP服务器
选项A：使用紫外线安装（推荐）
# Clone the repository
git clone https://github.com/your-username/bettertouchtool-mcp-server.git
cd bettertouchtool-mcp-server
# Install dependencies with uv
uv sync选项B：使用pip安装
# Clone the repository
git clone https://github.com/your-username/bettertouchtool-mcp-server.git
cd bettertouchtool-mcp-server
# Create virtual environment and install
python -m venv .venv
source .venv/bin/activate
pip install -e .3.配置克劳德桌面
将服务器添加到Claude Desktop配置文件中：
地点： ~/Library/Application Support/Claude/claude_desktop_config.json
使用紫外线：
{
"mcpServers": {
"bettertouchtool": {
"command": "uv",
"args": [
"--directory",
"/path/to/bettertouchtool-mcp-server",
"run",
"btt-mcp-server"
]
}
}
}直接使用Python：
{
"mcpServers": {
"bettertouchtool": {
"command": "/path/to/bettertouchtool-mcp-server/.venv/bin/python",
"args": ["-m", "btt_mcp"]
}
}
}4.重新启动克劳德桌面
保存配置后，重新启动Claude Desktop以加载MCP服务器。
可用工具
服务器提供20个工具，按类别组织：
配置读取
| 工具 | 说明 |
|---|---|
btt_get_triggers | 列表触发器，可选择按类型、应用程序或父级进行筛选 |
btt_get_trigger | 通过UUID获取特定触发器的详细信息 |
btt_list_named_triggers | 列出所有命名触发器（快速操作） |
btt_get_preset_details | 获取有关预设及其状态的信息 |
触发器管理
| 工具 | 说明 |
|---|---|
btt_trigger_named | 按名称执行命名触发器 |
btt_trigger_action | 通过JSON定义执行任何BTT操作 |
btt_execute_trigger | 执行分配给触发器UUID的所有操作 |
btt_add_trigger | 从JSON定义创建新触发器 |
btt_update_trigger | 修改现有触发器 |
btt_delete_trigger | 移除触发器(⚠️ 破坏性） |
变量管理
| 工具 | 说明 |
|---|---|
btt_get_variable | 读取字符串或数字变量 |
btt_set_variable | 设置持久或运行时变量 |
小部件控制
| 工具 | 说明 |
|---|---|
btt_update_widget | 更新小部件文本、图标或颜色 |
btt_refresh_widget | 强制刷新脚本小部件 |
剪贴板操作
| 工具 | 说明 |
|---|---|
btt_get_clipboard | 以各种格式读取剪贴板 |
btt_set_clipboard | 写入剪贴板 |
预设管理
| 工具 | 说明 |
|---|---|
btt_export_preset | 将预设导出到文件 |
btt_import_preset | 从文件导入预设 |
系统工具
| 工具 | 说明 |
|---|---|
btt_display_notification | 显示macOS通知 |
btt_reveal_in_ui | 打开BTT并导航到一个元素 |
用法示例
探索您的配置
问克劳德：
“我在BetterTouchTool中设置了哪些触发器？”
“显示我所有命名的触发器”
“我配置了哪些键盘快捷键？”
运行自动化
“在BTT中运行我的‘切换黑暗模式’触发器”
“执行打开我的开发环境的BTT触发器”
使用变量
“BTT中我的'workMode'变量的当前值是多少？”
“将我的BTT变量'currentProject'设置为'MCP服务器开发'”
更新小部件
“更新我的Touch Bar时钟小部件，以红色背景显示“5分钟后开会””
“刷新我的系统统计小部件”
管理配置
“将我当前的BTT预设导出到~/Desktop/my preset。bttpreset”
“显示UUID为abc-123-def的触发器的详细信息”
复杂的工作流程
“我想创建一个新的命名触发器，打开Safari并导航到我的项目管理工具”
“帮助我了解我的‘晨间例行’触发器的作用，并提出改进建议”
配置
配置存储在 ~/.config/btt-mcp/config.yml。该文件在首次使用时会自动创建，默认值为，也可以手动创建：
# BTT MCP Server Configuration
host: 127.0.0.1
port: 56786
shared_secret: null # Set this if you've configured a shared secret in BTT
use_cli: false # Set to true to use bttcli instead of HTTP配置选项
| 选项 | 默认值 | 描述 |
|---|---|---|
host | 127.0.0.1 | BTT网络服务器主机 |
port | 56786 | BTT Web服务器端口 |
shared_secret | null | 用于身份验证的共享密钥（如果在BTT中配置） |
use_cli | false | 使用 bttcli CLI工具而不是HTTP（更快，使用Unix套接字） |
示例：使用共享密钥
如果您在BTT首选项中配置了共享密钥：
host: 127.0.0.1
port: 56786
shared_secret: my_secret_key示例：使用CLI模式
为了使用Unix套接字获得更快的性能：
use_cli: true这使用了插座 /tmp/com.hegenberg.BetterTouchTool.sock 以降低延迟。
触发器类型
当筛选触发器时，您可以使用以下类型：
named_trigger-命名触发器（快速操作）keyboard_shortcut-键盘快捷键touchbar-触摸栏项目trackpad-触控板手势magic_mouse-魔术鼠标手势drawings-绘制手势siri_remote-Siri遥控器normal_mouse-常规鼠标按钮stream_deck-流甲板按钮midi-MIDI触发器menubar-菜单栏项目
故障排除
“连接被拒绝”错误
- 确保BTT正在运行
- 验证是否在BTT首选项中启用了Web服务器
- 检查端口是否匹配（默认值：12345）
“403禁止”错误
您在BTT中配置了共享密钥。要么：
- 添加
shared_secret: your_secret到~/.config/btt-mcp/config.yml - 从BTT首选项中删除共享密钥
“未找到bttcli”（CLI模式）
CLI工具应位于：
/Applications/BetterTouchTool.app/Contents/SharedSupport/bin/bttcli- 或
~/Applications/BetterTouchTool.app/Contents/SharedSupport/bin/bttcli
工具未出现在Claude中
- 检查Claude Desktop配置语法是否为有效的JSON
- 验证MCP服务器的路径是否正确
- 重新启动克劳德桌面
- 检查Console.app是否存在与MCP相关的错误
发展
项目结构
代码库被组织成一个模块化包：
src/btt_mcp/
├── server.py # FastMCP server initialization
├── config.py # Constants and configuration
├── models/ # Pydantic input models (7 files)
├── client/ # BTT communication (HTTP + CLI)
├── formatters/ # Output formatting
└── tools/ # MCP tool implementations (6 files)看 CLAUDE.md 获取详细的架构文档。
在本地运行以进行测试
# With uv
uv run btt-mcp-server
# Or directly
python -m btt_mcp运行测试
# Run all 48 tests
uv run pytest
# With verbose output
uv run pytest -vMCP检验员测试
npx @modelcontextprotocol/inspector uv --directory /path/to/project run btt-mcp-serverapi参考
此服务器实现 BTT网络服务器API.使用的关键端点：
GET /get_triggers-检索触发器配置GET /trigger_named-执行命名触发器GET /trigger_action-执行任意操作GET /get_string_variable/set_string_variable-变量管理GET /update_touch_bar_widget-小部件更新GET /get_clipboard_content/set_clipboard_content-剪贴板访问
许可证
MIT许可证-请参阅 许可证 文件。
贡献
欢迎投稿！请随时提交问题和拉取请求。
致谢
- BetterTouch工具 由folivora。人工智能
- 模型上下文协议 通过Anthropic
- 快速MCP Python MCP框架