BetterTouchTool MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like Claude to control and interact with BetterTouchTool on macOS.
What is this?
This MCP server acts as a bridge between Claude (or other MCP-compatible AI assistants) and BetterTouchTool, allowing you to:
- Query your BTT configuration - Understand what triggers, shortcuts, and automations you have set up
- Execute triggers and actions - Run named triggers, keyboard shortcuts, or any BTT action
- Manage variables - Get and set BTT variables for dynamic workflows
- Update widgets - Modify Touch Bar, Menu Bar, or Stream Deck widgets in real-time
- Control presets - Export, import, and manage BTT presets
- Access clipboard - Read and write clipboard contents programmatically
Prerequisites
- macOS (BetterTouchTool is macOS-only)
- BetterTouchTool installed with a valid license
- Python 3.12+
- uv (recommended) or pip for package management
- Claude Desktop or another MCP-compatible client
Installation
1. Enable BTT Webserver
First, enable the BetterTouchTool webserver:
- Open BetterTouchTool
- Go to Preferences → Advanced → Webserver
- Check Enable Webserver
- Note the port (default:
12345) - Optionally set a Shared Secret for authentication
2. Install the MCP Server
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 .
3. Configure Claude Desktop
Add the server to your Claude Desktop configuration file:
Location: ~/Library/Application Support/Claude/claude_desktop_config.json
Using uv:
{
"mcpServers": {
"bettertouchtool": {
"command": "uv",
"args": [
"--directory",
"/path/to/bettertouchtool-mcp-server",
"run",
"btt_mcp.py"
]
}
}
}
Using Python directly:
{
"mcpServers": {
"bettertouchtool": {
"command": "/path/to/bettertouchtool-mcp-server/.venv/bin/python",
"args": ["/path/to/bettertouchtool-mcp-server/btt_mcp.py"]
}
}
}
4. Restart Claude Desktop
After saving the configuration, restart Claude Desktop to load the MCP server.
Available Tools
The server provides 20 tools organized into categories:
Configuration Reading
| Tool | Description |
|---|---|
btt_get_triggers | List triggers with optional filtering by type, app, or parent |
btt_get_trigger | Get detailed info about a specific trigger by UUID |
btt_list_named_triggers | List all named triggers (quick actions) |
btt_get_preset_details | Get info about presets and their status |
Trigger Management
| Tool | Description |
|---|---|
btt_trigger_named | Execute a named trigger by name |
btt_trigger_action | Execute any BTT action via JSON definition |
btt_execute_trigger | Execute all actions assigned to a trigger UUID |
btt_add_trigger | Create a new trigger from JSON definition |
btt_update_trigger | Modify an existing trigger |
btt_delete_trigger | Remove a trigger (⚠️ destructive) |
Variable Management
| Tool | Description |
|---|---|
btt_get_variable | Read string or number variables |
btt_set_variable | Set persistent or runtime variables |
Widget Control
| Tool | Description |
|---|---|
btt_update_widget | Update widget text, icon, or colors |
btt_refresh_widget | Force a script widget to refresh |
Clipboard Operations
| Tool | Description |
|---|---|
btt_get_clipboard | Read clipboard in various formats |
btt_set_clipboard | Write to clipboard |
Preset Management
| Tool | Description |
|---|---|
btt_export_preset | Export preset to a file |
btt_import_preset | Import preset from a file |
System Utilities
| Tool | Description |
|---|---|
btt_display_notification | Show a macOS notification |
btt_reveal_in_ui | Open BTT and navigate to an element |
Usage Examples
Exploring Your Configuration
Ask Claude:
"What triggers do I have set up in BetterTouchTool?"
"Show me all my named triggers"
"What keyboard shortcuts do I have configured?"
Running Automations
"Run my 'Toggle Dark Mode' trigger in BTT"
"Execute the BTT trigger that opens my development environment"
Working with Variables
"What's the current value of my 'workMode' variable in BTT?"
"Set my BTT variable 'currentProject' to 'MCP Server Development'"
Updating Widgets
"Update my Touch Bar clock widget to show 'Meeting in 5 min' with a red background"
"Refresh my system stats widget"
Managing Configuration
"Export my current BTT preset to ~/Desktop/my-preset.bttpreset"
"Show me the details of trigger with UUID abc-123-def"
Complex Workflows
"I want to create a new named trigger that opens Safari and navigates to my project management tool"
"Help me understand what my 'Morning Routine' trigger does and suggest improvements"
Connection Options
Default HTTP Connection
By default, tools connect via HTTP to 127.0.0.1:12345. No additional configuration needed if BTT webserver is enabled with default settings.
With Shared Secret
If you've configured a shared secret in BTT, include it in your requests:
Use my BTT shared secret "my_secret_key" when connecting
Or Claude will ask if authentication fails.
Using CLI Mode
For faster performance, you can use the bttcli command-line tool instead of HTTP:
Use CLI mode for BTT commands
This uses the Unix socket at /tmp/com.hegenberg.BetterTouchTool.sock for lower latency.
Trigger Types
When filtering triggers, you can use these types:
named_trigger- Named triggers (quick actions)keyboard_shortcut- Keyboard shortcutstouchbar- Touch Bar itemstrackpad- Trackpad gesturesmagic_mouse- Magic Mouse gesturesdrawings- Drawing gesturessiri_remote- Siri Remotenormal_mouse- Regular mouse buttonsstream_deck- Stream Deck buttonsmidi- MIDI triggersmenubar- Menu bar items
Troubleshooting
"Connection refused" errors
- Ensure BTT is running
- Verify webserver is enabled in BTT preferences
- Check the port matches (default: 12345)
"403 Forbidden" errors
You have a shared secret configured in BTT. Either:
- Provide the secret in your request
- Remove the shared secret from BTT preferences
"bttcli not found" (CLI mode)
The CLI tool should be at:
/Applications/BetterTouchTool.app/Contents/SharedSupport/bin/bttcli- or
~/Applications/BetterTouchTool.app/Contents/SharedSupport/bin/bttcli
Tools not appearing in Claude
- Check Claude Desktop config syntax is valid JSON
- Verify the path to the MCP server is correct
- Restart Claude Desktop
- Check Console.app for MCP-related errors
Development
Running locally for testing
# With uv
uv run btt_mcp.py
# Or directly
python btt_mcp.py
Testing with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory /path/to/project run btt_mcp.py
API Reference
This server implements the BTT Webserver API. Key endpoints used:
GET /get_triggers- Retrieve trigger configurationsGET /trigger_named- Execute named triggersGET /trigger_action- Execute arbitrary actionsGET /get_string_variable/set_string_variable- Variable managementGET /update_touch_bar_widget- Widget updatesGET /get_clipboard_content/set_clipboard_content- Clipboard access
License
MIT License - see LICENSE file.
Contributing
Contributions welcome! Please feel free to submit issues and pull requests.
Acknowledgments
- BetterTouchTool by folivora.AI
- Model Context Protocol by Anthropic
- FastMCP for the Python MCP framework