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:

1. Open BetterTouchTool
2. Go to Preferences → Advanced → Webserver
3. Check Enable Webserver
4. Note the port (default: 12345)
5. 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 shortcuts
• touchbar - Touch Bar items
• trackpad - Trackpad gestures
• magic_mouse - Magic Mouse gestures
• drawings - Drawing gestures
• siri_remote - Siri Remote
• normal_mouse - Regular mouse buttons
• stream_deck - Stream Deck buttons
• midi - MIDI triggers
• menubar - Menu bar items

Troubleshooting

"Connection refused" errors

1. Ensure BTT is running
2. Verify webserver is enabled in BTT preferences
3. 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

1. Check Claude Desktop config syntax is valid JSON
2. Verify the path to the MCP server is correct
3. Restart Claude Desktop
4. 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 configurations
• GET /trigger_named - Execute named triggers
• GET /trigger_action - Execute arbitrary actions
• GET /get_string_variable / set_string_variable - Variable management
• GET /update_touch_bar_widget - Widget updates
• GET /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