Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BTT_HOST | No | The host address for the BetterTouchTool webserver | 127.0.0.1 |
| BTT_PORT | No | The port number for the BetterTouchTool webserver | 12345 |
| BTT_SHARED_SECRET | No | The shared secret configured in BetterTouchTool webserver for authentication (optional) |
Capabilities
Features and capabilities supported by this server
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| btt_get_triggers | Retrieve triggers from BetterTouchTool with optional filtering. Use this tool to explore and understand the current BTT configuration.
You can filter by trigger type, parent folder, specific app, or get all triggers.
Args:
params: Filter parameters including trigger_type, trigger_id, app_bundle_identifier, etc.
Returns:
List of triggers in markdown or JSON format based on response_format setting. |
| btt_get_trigger | Retrieve a specific trigger by its UUID. Use this to get detailed information about a single trigger, including
all its configuration and assigned actions.
Args:
params: Contains the UUID of the trigger to retrieve.
Returns:
Trigger configuration in markdown or JSON format. |
| btt_list_named_triggers | List all named triggers configured in BetterTouchTool. Named triggers are triggers configured in the 'Other' tab that can be
called by name from scripts or other actions.
Returns:
List of named triggers with their names and UUIDs. |
| btt_trigger_named | Execute a named trigger by its name. Named triggers are configured in BTT's 'Other' tab and can perform
any sequence of actions.
Args:
params: Contains the trigger_name and whether to wait for completion.
Returns:
Result of the trigger execution (if wait_for_reply is True). |
| btt_trigger_action | Trigger any BTT predefined action using a JSON definition. You can get the JSON for an action by right-clicking a configured
trigger in BTT and selecting 'Copy JSON'.
Args:
params: Contains the action JSON definition.
Returns:
Result of the action execution. |
| btt_execute_trigger | Execute all actions assigned to a specific trigger by UUID. Args:
params: Contains the UUID of the trigger to execute.
Returns:
Result of the execution. |
| btt_add_trigger | Add a new trigger to BetterTouchTool. The trigger definition should be in JSON format. You can get
the format by copying an existing trigger's JSON in BTT.
Args:
params: Contains the trigger JSON definition and optional parent UUID.
Returns:
Confirmation of trigger creation. |
| btt_update_trigger | Update an existing trigger's configuration. Provide the UUID of the trigger and a JSON object with the
properties to update.
Args:
params: Contains UUID and JSON with properties to update.
Returns:
Confirmation of update. |
| btt_delete_trigger | Delete a trigger from BetterTouchTool. WARNING: This permanently removes the trigger. Make sure you have
the correct UUID before deleting.
Args:
params: Contains the UUID of the trigger to delete.
Returns:
Confirmation of deletion. |
| btt_get_variable | Get the value of a BTT variable. BTT has many built-in variables (like BTTActiveAppBundleIdentifier)
and supports user-defined variables.
Args:
params: Variable name and type (string or number).
Returns:
Current value of the variable. |
| btt_set_variable | Set a BTT variable to a specified value. Variables can be persistent (survive BTT restart) or runtime-only.
Args:
params: Variable name, value, type, and persistence setting.
Returns:
Confirmation of variable being set. |
| btt_update_widget | Update the display of a Touch Bar, Menubar, or Stream Deck widget. This allows temporary updates to widget appearance without changing
the underlying configuration.
Args:
params: Widget UUID, type, and display properties to update.
Returns:
Confirmation of widget update. |
| btt_refresh_widget | Refresh a script widget to re-execute its scripts. Use this to force a widget to update its display by running
its assigned scripts again.
Args:
params: UUID of the widget to refresh.
Returns:
Confirmation of refresh. |
| btt_get_clipboard | Get the current clipboard content. Can retrieve content in various formats including plain text, HTML,
images (as base64), and more.
Args:
params: Format to retrieve and whether to return as base64.
Returns:
Clipboard content. |
| btt_set_clipboard | Set the clipboard content. Can set content in various formats including plain text and HTML.
Args:
params: Content to set and format.
Returns:
Confirmation of clipboard being set. |
| btt_export_preset | Export a BTT preset to a file. Useful for backing up configurations or sharing presets.
Args:
params: Preset name and export options.
Returns:
Path to exported preset file. |
| btt_import_preset | Import a BTT preset from a file. Args:
params: Path to the preset file.
Returns:
Confirmation of import. |
| btt_get_preset_details | Get details about a specific preset. Returns information about the preset's status, UUID, and visibility.
Args:
params: Name of the preset to query.
Returns:
Preset details in markdown or JSON format. |
| btt_display_notification | Display a macOS notification via BTT. Args:
params: Notification title, subtitle, sound, and optional image.
Returns:
Confirmation of notification being displayed. |
| btt_reveal_in_ui | Reveal a trigger or element in the BetterTouchTool UI. Opens BTT and navigates to the specified element for editing.
Args:
params: UUID of the element to reveal.
Returns:
Confirmation. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |