使用说明

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 -v

MCP检验员测试

npx @modelcontextprotocol/inspector uv --directory /path/to/project run btt-mcp-server

api参考

此服务器实现 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框架