BetterTouchTool MCP Server

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服务器：

1. 打开BetterTouchTool
2. 首选 偏好 → 高级 → Web服务器
3. 检查 启用Web服务器
4. 注意端口（默认值： 56786)
5. 可选择设置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个工具，按类别组织：

配置读取

触发器管理

变量管理

小部件控制

剪贴板操作

预设管理

系统工具

用法示例

探索您的配置

问克劳德：

“我在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

配置选项

示例：使用共享密钥

如果您在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 -菜单栏项目

故障排除

“连接被拒绝”错误

1. 确保BTT正在运行
2. 验证是否在BTT首选项中启用了Web服务器
3. 检查端口是否匹配（默认值：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中

1. 检查Claude Desktop配置语法是否为有效的JSON
2. 验证MCP服务器的路径是否正确
3. 重新启动克劳德桌面
4. 检查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框架