bettertouchtool

BetterTouchTool MCP Server acts as a bridge between Claude (or any MCP-compatible AI) and BetterTouchTool on macOS. It exposes a suite of tools that let you query your BTT configuration, execute triggers and actions, manage variables, update widgets, handle presets, and access clipboard content. With the server running, you can ask your AI to list triggers, run a named trigger, read or set BTT variables, or update widgets in real-time, enabling dynamic, AI-driven automations across your macOS setup.

To use it, configure Claude Desktop (or your MCP client) to point at the MCP server. The README provides two deployment options depending on your environment: using uv to run the server from source, or using Python to run the module directly. Once configured, you can invoke the provided tools via natural language prompts like “What triggers do I have in BTT?”, “Run my 'Toggle Dark Mode' trigger in BTT”, or “Set the BTT variable 'currentProject' to 'MCP Server Development'.” The tools are organized into categories such as Configuration Reading, Trigger Management, Variable Management, Widget Control, Clipboard Operations, Preset Management, and System Utilities, giving you fine-grained control over every aspect of BTT from your AI client.

Prerequisites to install:

• macOS with BetterTouchTool installed and licensed
• Python 3.12+ or uv (recommended)
• Claude Desktop or another MCP-compatible client

Installation options:

Option A: Install with uv (Recommended)

# Clone the repository
git clone https://github.com/your-username/bettertouchtool-mcp-server.git
cd bettertouchtool-mcp-server

# Install dependencies with uv
uv sync

Option B: Install with 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 .

Configure Claude Desktop

You can add the MCP server to Claude Desktop configuration. Example configurations are provided in the README for using uv or Python directly. Replace paths with your actual installation paths. After saving the config, restart Claude Desktop to load the MCP server.

Tips and common issues:

• Ensure the BTT webserver is enabled in BetterTouchTool and that the port matches the one configured in your MCP setup (default 56786).
• If you enable a shared secret in BTT, you may need to add shared_secret to Claude config or disable the secret in BTT to avoid 403 errors.
• In CLI mode, bttcli location must be accessible; if not, verify the executable path in BTT preferences.
• When using uv, specify the correct directory to your server project and the module or entrypoint name as shown in the README examples.
• If Tools do not appear in Claude, verify the Claude config JSON syntax, the MCP server path, and check system logs for MCP-related errors.
• Configuration details such as host, port, shared_secret, and use_cli can be stored in a YAML config as described in the README for easier management.