Skip to main content
Glama
homelab-admin

BetterTouchTool MCP Server

by homelab-admin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
BTT_HOSTNoThe host address for the BetterTouchTool webserver127.0.0.1
BTT_PORTNoThe port number for the BetterTouchTool webserver12345
BTT_SHARED_SECRETNoThe shared secret configured in BetterTouchTool webserver for authentication (optional)

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
btt_get_triggersA

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_triggerA

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_triggersA

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_namedA

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_actionA

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_triggerB

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_triggerA

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_triggerB

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_triggerA

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_variableA

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_variableA

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_widgetA

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_widgetA

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_clipboardB

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_clipboardB

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_presetA

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_presetB

Import a BTT preset from a file.

Args:
    params: Path to the preset file.

Returns:
    Confirmation of import.
btt_get_preset_detailsB

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_notificationB

Display a macOS notification via BTT.

Args:
    params: Notification title, subtitle, sound, and optional image.

Returns:
    Confirmation of notification being displayed.
btt_reveal_in_uiA

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 20 tools

Disambiguation4/5

Most tools have distinct purposes, but there is some potential confusion between btt_execute_trigger, btt_trigger_action, and btt_trigger_named, as they all involve executing triggers or actions. The descriptions help clarify differences, but an agent might initially struggle to choose the right one for a given task.

Naming Consistency5/5

All tool names follow a consistent btt_verb_noun pattern with snake_case, such as btt_add_trigger, btt_delete_trigger, and btt_get_clipboard. This uniformity makes the tool set predictable and easy to navigate.

Tool Count4/5

With 20 tools, the count is on the higher side but reasonable for a comprehensive BetterTouchTool server covering triggers, presets, variables, clipboard, notifications, and widgets. It might feel slightly heavy, but each tool appears to serve a specific function in the domain.

Completeness5/5

The tool set provides complete coverage for managing BetterTouchTool, including CRUD operations for triggers (add, delete, get, update, list), preset handling (export, import, get details), variable management (get, set), clipboard control, notifications, and widget updates. No obvious gaps are present for the intended domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources