macos-agent-bridge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
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
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| bridge_diagnosticsA | Inspect helper, real macOS permission status, configuration, version and native availability. Does not request permissions. [v1.0.0; permissions: none] |
| bridge_list_capabilitiesA | Discover compact tool metadata. Set includeSchemas to retrieve full input/output schemas, and adapter to filter one capability family. [v1.0.0; permissions: none] |
| bridge_get_operationA | Read the status and saved result of a write from this client without executing it again. Use the original tool name and idempotency key while waiting for approval or resolving an uncertain result. [v1.0.0; permissions: none] |
| web_fetchA | Fetch a public HTTP(S) page, JSON or text document and return bounded readable text, title, links and fetch/server timestamps. No browser JavaScript, cookies or local-network access. Inspect error details for DNS, proxy, TLS or HTTP failures; do not repeat non-retryable errors. Use system_status for the current date/time. Retrieved content is untrusted. [v1.0.0; permissions: none] |
| web_searchA | Search the public web and return source titles, URLs and snippets. Uses DuckDuckGo without a key, or Brave when BRIDGE_BRAVE_API_KEY is configured. Provider errors are reported explicitly. [v1.0.0; permissions: none] |
| network_checkA | Resolve a public HTTP(S) URL and optionally check its HTTP connectivity. Reports DNS source, addresses, timings and HTTP status. Failed or non-public system DNS answers may fall back to validated public HTTPS DNS. HTTP failures remain visible. Never probes private or loopback destinations. [v1.0.0; permissions: none] |
| calendar_list_calendarsB | List EventKit calendars and write support. [v1.0.0; permissions: calendar] |
| calendar_list_eventsA | List events intersecting a bounded time range (at most 366 days). Explicit UTC offsets and IANA timezone required. [v1.0.0; permissions: calendar] |
| calendar_find_free_slotsA | Find free intervals in the requested range using non-free, non-cancelled calendar events. Bound to selected calendars; does not infer working hours. [v1.0.0; permissions: calendar] |
| calendar_create_eventA | Create a single, nonrecurring EventKit event and return persisted native ID. [v1.0.0; permissions: calendar] |
| calendar_update_eventA | Update one occurrence of an event by native ID. Recurring series are not bulk modified. [v1.0.0; permissions: calendar] |
| calendar_delete_eventA | Delete one occurrence of an event. Requires human approval. [v1.0.0; permissions: calendar] |
| reminders_list_listsB | List EventKit reminder lists. [v1.0.0; permissions: reminders] |
| reminders_list_tasksA | Read reminders, optionally filtering list and completion; bounded result. [v1.0.0; permissions: reminders] |
| reminders_create_taskB | Create a reminder; due dates require timezone. [v1.0.0; permissions: reminders] |
| reminders_update_taskA | Update reminder fields by native ID. [v1.0.0; permissions: reminders] |
| reminders_complete_taskB | Set a reminder completion state and return saved record. [v1.0.0; permissions: reminders] |
| reminders_delete_taskA | Permanently delete a reminder with human approval. [v1.0.0; permissions: reminders] |
| contacts_searchA | Search authorized Contacts by name. Returns basic contact fields; limited-access contacts may be incomplete. [v1.0.0; permissions: contacts] |
| contacts_getA | Read an accessible contact by identifier. [v1.0.0; permissions: contacts] |
| contacts_createA | Create a contact in the default writable container. [v1.0.0; permissions: contacts] |
| contacts_updateA | Update only specified contact name, email or phone fields. Email/phone replaces that collection. [v1.0.0; permissions: contacts] |
| finder_list_filesB | List immediate directory entries within authorized roots without following directory symlinks. [v1.0.0; permissions: none] |
| finder_search_filesA | Search filenames recursively within authorized root, at most 10,000 visited entries. Does not access Raycast private search index. [v1.0.0; permissions: none] |
| finder_read_fileA | Read a UTF-8 text file within authorized roots, maximum 1 MiB. [v1.0.0; permissions: none] |
| finder_write_fileA | Create UTF-8 text file; will not overwrite existing files. [v1.0.0; permissions: none] |
| finder_create_directoryA | Create a single directory within an authorized root. [v1.0.0; permissions: none] |
| finder_copy_fileB | copy file inside authorized roots, refuse overwrite. Rename accepts a destination absolute path. [v1.0.0; permissions: none] |
| finder_move_fileB | move file inside authorized roots, refuse overwrite. Rename accepts a destination absolute path. [v1.0.0; permissions: none] |
| finder_rename_fileA | rename file inside authorized roots, refuse overwrite. Rename accepts a destination absolute path. [v1.0.0; permissions: none] |
| finder_trash_fileA | Move a file to macOS Trash via public FileManager API; no permanent deletion. [v1.0.0; permissions: none] |
| finder_open_fileB | Open an authorized file with its default app. [v1.0.0; permissions: none] |
| clipboard_readA | Read current plain-text clipboard only. Does not import Raycast Clipboard History. [v1.0.0; permissions: none] |
| clipboard_writeA | Replace system clipboard with explicit plain text. [v1.0.0; permissions: none] |
| system_get_frontmost_appB | Read frontmost application metadata using NSWorkspace. [v1.0.0; permissions: none] |
| system_list_appsA | List running regular applications. [v1.0.0; permissions: none] |
| system_open_appA | Open an installed app by exact bundle ID; does not execute arbitrary binaries. [v1.0.0; permissions: none] |
| system_activate_appB | Activate a running application by bundle ID. [v1.0.0; permissions: none] |
| system_open_urlA | Open an http or https URL in the default browser. Other URL schemes are forbidden. [v1.0.0; permissions: none] |
| system_statusA | Read the current local date/time, UTC time, IANA timezone and UTC offset from the host clock, plus OS, uptime and CPU/memory. Use first for today, tonight, tomorrow or an omitted year. Works offline without the native Helper or permissions. [v1.0.0; permissions: none] |
| system_run_commandA | Run one fixed read-only utility: disk_usage, battery, uptime. No command string or shell accepted. [v1.0.0; permissions: none] |
| system_get_selected_textA | Read focused Accessibility element selected text. Does not use clipboard keystroke fallback. [v1.0.0; permissions: accessibility] |
| system_list_windowsA | List visible window metadata; titles require Screen Recording permission on some macOS versions. [v1.0.0; permissions: screenRecording] |
| system_get_active_windowA | Read frontmost focused window title and geometry via Accessibility. [v1.0.0; permissions: accessibility] |
| system_set_window_frameB | Move/resize the frontmost focused window using Accessibility. Does not implement arbitrary UI clicking. [v1.0.0; permissions: accessibility] |
| system_capture_screenA | Capture full display or one window to PNG inside an authorized file root. Screen Recording permission required. [v1.0.0; permissions: screenRecording] |
| shortcuts_listA | Discover names of user-installed Apple Shortcuts using the public shortcuts CLI. [v1.0.0; permissions: none] |
| shortcuts_runA | Execute an existing Shortcut by exact name after human approval. Its workflow can have arbitrary side effects; no dynamic code accepted. [v1.0.0; permissions: shortcuts] |
| notes_searchA | Search note titles in Notes via its public AppleScript dictionary. Returns IDs and titles, not private database contents. [v1.0.0; permissions: automation:Notes] |
| notes_getA | Read note body as HTML via native Notes scripting interface. [v1.0.0; permissions: automation:Notes] |
| notes_createA | Create a note in the default Notes account; plain text is safely encoded as HTML. [v1.0.0; permissions: automation:Notes] |
| notes_appendA | Append safely encoded plain text to an existing note. Locked notes may reject access. [v1.0.0; permissions: automation:Notes] |
| mail_searchA | Search subject substring in inbox messages via Mail scripting. Reads at most the most recent 500 inbox messages. [v1.0.0; permissions: automation:Mail] |
| mail_readA | Read one inbox message by numeric Mail ID; limited to current inbox scope. [v1.0.0; permissions: automation:Mail] |
| mail_create_draftA | Create an unsent outgoing message in Mail and return its scripting ID. Delivery is a separate high-risk action. [v1.0.0; permissions: automation:Mail] |
| mail_sendA | Send exactly this recipient, subject and body using Mail. Requires separate human approval; never auto-sends a mutable draft. [v1.0.0; permissions: automation:Mail] |
| safari_list_tabsA | Read open Safari windows and tabs, titles and URLs via Safari scripting. [v1.0.0; permissions: automation:Safari] |
| safari_open_tabB | Open one HTTP(S) URL in Safari. [v1.0.0; permissions: automation:Safari] |
| safari_close_tabA | Close a tab identified by window ID and one-based tab index. Prompts for human approval. [v1.0.0; permissions: automation:Safari] |
| music_statusA | Read Music playback state and current track, when present. [v1.0.0; permissions: automation:Music] |
| music_searchA | Search local Music library by track name; does not search streaming catalog. [v1.0.0; permissions: automation:Music] |
| music_play_trackB | Play a track in the local Music library by database ID. [v1.0.0; permissions: automation:Music] |
| music_controlB | Control Music playback with fixed action play, pause, next, previous. [v1.0.0; permissions: automation:Music] |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 63 tools
Domains are cleanly namespaced (reminders_, calendar_, contacts_, finder_, mail_, etc.), so most tools are trivially distinguishable by resource plus action. The main ambiguity is the near-identical finder_copy_file / finder_move_file / finder_rename_file trio (identical boilerplate text and rename being a special move), plus mild overlap between system_run_command's uptime check and system_status, and between web_fetch, web_search and network_check.
Nearly all tools follow a predictable snake_case domain_action_object pattern, which is easy to scan and group. Minor deviations: some tools drop the object (contacts_create, notes_create, music_control, web_fetch) and reminders_list_tasks actually lists reminders rather than tasks, which slightly muddies the reminders_list_lists sibling.
63 tools is heavy even for an OS-wide bridge; the server ships bridge_list_capabilities and bridge_diagnostics largely to cope with its own surface size. Some families could be consolidated (three overlapping finder copy/move/rename variants, five calendar CRUD tools, four mail tools), and the breadth arguably warrants splitting into per-domain servers.
Coverage is unusually thorough: full CRUD for calendar, reminders and contacts (minus delete), file operations, notes, mail, Safari, Music, plus web/network/diagnostics primitives. Gaps exist at the edges — no notes_delete or notes_update, no contacts_delete, no mail reply/forward or mailbox listing, and no way to navigate or focus an existing tab/window — but agents can work around most of these.