Which integrations are available for this server?

Enables control and interaction with BetterTouchTool on [macOS](/mcp/servers/integrations/macos), allowing management of triggers, shortcuts, automations, variables, Touch Bar/Menu Bar widgets, presets, and clipboard operations.

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

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

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