This macOS Agent Bridge MCP server exposes local Mac capabilities through shared permissions, approvals, and idempotent write flows.
Inspect bridge diagnostics, discover tool capabilities, and check operation/approval status.
Search/fetch public web content and diagnose DNS/HTTP/network connectivity.
List, query, create, update, and delete calendars/events and reminders/tasks.
Search, read, create, and update contacts.
Browse, search, read, write, copy, move, rename, trash, and open files only within authorized roots.
Read/write clipboard; inspect, open, and activate apps; open HTTP(S) URLs; read system status, windows, and selected text; move/resize windows; capture screenshots; run fixed read-only commands.
List and run installed Apple Shortcuts with human approval.
Search/read/create/append Notes; search/read Mail, create drafts, and send mail with approval.
List/open/close Safari tabs and inspect/search/play/control local Music.
Write operations require an idempotency key; destructive or high-risk actions require explicit human approval, and many tools require macOS permissions.
Provides tools for interacting with Apple applications and frameworks, including Contacts, Notes, Mail, Music, Calendar, and Reminders via EventKit and fixed public script interfaces.
Enables AI to invoke native macOS capabilities such as Calendar, Reminders, file operations, desktop and system tools, and Apple application scripting through a unified bridge.
Integrates with Raycast as an extension host, providing commands to manage capabilities, file scopes, auto-approval, system permissions, review pending agent actions, view activity logs, preview calendar events, and copy MCP configuration.
Allows AI to interact with Safari through fixed public script interfaces as part of its Apple application support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@macos-agent-bridge what's on my calendar tomorrow, and remind me to email the team at 3pm?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
让 AI 通过 MCP 调用 Mac 的日历、提醒事项、文件和桌面能力，在 Tinycast / Raycast 扩展中统一管理能力开关、权限、待确认操作与审计记录。独立 MCP 客户端也能使用同一套工具。
63 个工具定义 · 5 个扩展命令 · 本地运行。工具数量不等于全部能力均已实机验收，逐项状态见能力覆盖矩阵。
下载 v0.3.0 · 快速开始 · 能力与边界 · 安全说明
完成安装与 MCP 连接后，在 Tinycast AI Chat 中试试：
@macos-bridge 查询当前本地日期、时间、时区和系统运行时间。
也可以让 Agent 列出可用日历、查询指定时间段的空闲，或搜索并读取公开网页。日历等资源需要对应的 macOS 权限；联网工具需要网络连接。
开发者可直接调用同名 MCP 工具：
{"name":"system_status","arguments":{}}system_status 直接读取本机时钟，返回 localDate、带 UTC 偏移的 localTime、UTC currentTime、IANA timezone 和 unixTimeMs，不需要联网、Helper 或系统授权。处理“今天晚上”“明天”时先调用它。网页获取失败时，查看错误中的 phase、causeCode 和 hint。系统 DNS 异常时默认回退到 Cloudflare HTTPS DNS，仅发送域名，可通过 BRIDGE_DNS_FALLBACK=off 关闭；详见日期与联网故障排查。
所有调用返回统一的 ok、error 或 confirmation_required 状态。待确认表示尚未执行；在扩展里审阅参数并批准后，Agent 可用原幂等键取得结果。
Related MCP server: osa-mcp
v0.3.0 为公开开发版本。 预构建包面向 Apple Silicon，Helper 使用 ad-hoc 签名，尚未完成 Developer ID 公证或商店审核。macOS 可能阻止首次打开；参阅发行与安全说明，也可选择从源码构建。
从 Release 下载 macos-agent-bridge-macos-arm64.zip 和 SHA256SUMS，在下载目录校验后解压：
shasum -a 256 -c SHA256SUMS运行解压目录中的 Install.command。安装包包含 Node 运行时、Swift Helper 和已构建扩展，无需另外安装 Node 或 Swift。
需要 macOS 14+、Node.js 22+、Xcode Command Line Tools / Swift；使用的启动器还需满足自身系统要求。
git clone https://github.com/juliusloon/macos-agent-bridge.git
cd macos-agent-bridge
npm ci
npm run install:local安装器编译运行组件，并为当前用户生成扩展与 MCP 配置。重新安装前，先退出正在运行的 MacOS Agent Bridge Helper。
Tinycast：Settings → Extensions → Add from folder，选择安装包内的 Extension/；源码安装选择 raycast-extension/dist/。
Raycast：Import Extension 选择 raycast-extension/ 源码目录。在扩展设置中将 Bridge launcher 指向已安装的 bridge 文件。
安装后的入口：
命令 | 用途 |
macOS Agent Bridge | 管理能力、文件范围、自动批准与系统权限 |
Review Agent Actions | 审阅具体参数，批准并执行或拒绝 |
Agent Bridge Activity | 查看脱敏的操作状态记录 |
Bridge Calendar | 预览未来七天日程 |
Connect Tinycast AI Chat | 复制当前用户的 MCP 配置 |
在 Connect Tinycast AI Chat 中复制配置。Tinycast 的入口为 Settings → AI → MCP Servers：Connection 选 Command，填入安装器生成的启动路径，Arguments 填 --serve。测试连接应发现 63 个工具。
导入扩展与连接 MCP 是两个步骤。 服务启动后无需持续打开管理界面；Tinycast AI Chat 需使用支持 MCP 工具的模型连接。
其他 MCP 客户端使用相同的 stdio 配置：
{
"mcpServers": {
"macos-agent-bridge": {
"command": "/Users/<用户名>/Library/Application Support/MacOSAgentBridge/bridge",
"args": ["--serve"]
}
}
}上方路径是占位示例，不能直接粘贴使用。优先复制扩展提供的真实配置；源码安装也会生成 docs/mcp-client.json。不要假设 MCP 客户端会自动展开 ~ 或环境变量。
能力组 | 接入内容与范围 |
日历与提醒事项 | EventKit 列表、查询与写入接口；时间参数明确 UTC 偏移和时区 |
文件 | 仅用户授权根目录内的搜索、文本读写、复制与移动等操作 |
桌面与系统 | 应用、当前剪贴板、窗口、截图及固定只读系统命令 |
Apple 应用 | Contacts；Notes、Mail、Safari、Music 的固定公开脚本接口 |
快捷指令 | 枚举和运行已安装的 Shortcuts；执行始终需要确认 |
公网工具 |
|
这些是接口范围；Contacts、Accessibility、截图及部分应用写入仍有权限或验收限制。完整支持状态与限制以覆盖矩阵为准。
不提供任意 shell、任意 AppleScript / JavaScript 执行，也不读取 Raycast 私有的 Clipboard History、Notes、Snippets 或 Quicklinks 数据库。
默认逐次审批写入。 用户可开启普通写入自动批准或信任指定能力；删除、发送邮件、运行快捷指令等高风险操作仍需明确批准。
重试沿用同一幂等键。 审批绑定具体工具、参数和来源；不确定的执行结果需先核实，避免重复写入。
文件访问有范围。 默认工作目录为 ~/Documents/Agent Bridge Workspace，不会自动授权整个主目录。
本地通信与状态。 MCP 使用 stdio；Swift Helper 使用当前用户的 Unix socket。审计日志记录状态，不记录正文或参数；待审批参数与短期执行结果会保存在本地状态中。
联网有明确边界。 公网工具不读取浏览器 Cookie，不执行网页脚本；搜索词和请求 URL 会发送给相应服务。选定的 AI 客户端如何处理工具结果，由该客户端决定。
macOS 系统授权、启动器的 MCP 信任设置、Bridge 的动作审批分别生效。详细保存规则与威胁边界见安全说明。
npm run check
npm test
npm run build
npm run build:native
npm run build:extension原生工具的实际行为取决于系统权限、应用账户与宿主支持。自动测试通过不代表全部原生读写已经实机验证；公开验证范围见验收说明。
文档 | 内容 |
MCP、共享执行引擎与 Swift Helper | |
导入、MCP 连接和审批流程 | |
逐工具状态、权限、限制 | |
审批、文件边界、本地数据、发行签名 | |
自动批准、联网与操作状态查询 | |
运行时与依赖许可证 | |
参与开发、报告漏洞与版本记录 |
欢迎通过 Issues 反馈可复现的问题，或提交改进。报告中请使用占位数据，不上传日程、联系人、邮件正文或完整本地状态目录。
MIT © 2026 Cano and contributors。第三方组件保留各自许可证。
Inspect helper, real macOS permission status, configuration, version and native availability. Does not request permissions. [v1.0.0; permissions: none]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
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]
Inputs: tool (required), idempotencyKey (required). Returns: data, tool, error, status, +1 more
Discover compact tool metadata. Set includeSchemas to retrieve full input/output schemas, and adapter to filter one capability family. [v1.0.0; permissions: none]
Inputs: adapter, includeSchemas. Returns: data, tool, error, status, +1 more
Create a single, nonrecurring EventKit event and return persisted native ID. [v1.0.0; permissions: calendar]
Inputs: end (required), start (required), title (required), timezone (required), +5 more. Returns: data, tool, error, status, +1 more
Delete one occurrence of an event. Requires human approval. [v1.0.0; permissions: calendar]
Inputs: id (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
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]
Inputs: end (required), start (required), timezone (required), durationMinutes (required), +1 more. Returns: data, tool, error, status, +1 more
List EventKit calendars and write support. [v1.0.0; permissions: calendar]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
List events intersecting a bounded time range (at most 366 days). Explicit UTC offsets and IANA timezone required. [v1.0.0; permissions: calendar]
Inputs: end (required), start (required), timezone (required), limit, +1 more. Returns: data, tool, error, status, +1 more
Update one occurrence of an event by native ID. Recurring series are not bulk modified. [v1.0.0; permissions: calendar]
Inputs: id (required), _idempotencyKey (required), end, notes, +6 more. Returns: data, tool, error, status, +1 more
Read current plain-text clipboard only. Does not import Raycast Clipboard History. [v1.0.0; permissions: none]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
Replace system clipboard with explicit plain text. [v1.0.0; permissions: none]
Inputs: text (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Create a contact in the default writable container. [v1.0.0; permissions: contacts]
Inputs: givenName (required), _idempotencyKey (required), email, phone, +2 more. Returns: data, tool, error, status, +1 more
Read an accessible contact by identifier. [v1.0.0; permissions: contacts]
Inputs: id (required). Returns: data, tool, error, status, +1 more
Search authorized Contacts by name. Returns basic contact fields; limited-access contacts may be incomplete. [v1.0.0; permissions: contacts]
Inputs: query (required), limit. Returns: data, tool, error, status, +1 more
Update only specified contact name, email or phone fields. Email/phone replaces that collection. [v1.0.0; permissions: contacts]
Inputs: id (required), _idempotencyKey (required), email, phone, +3 more. Returns: data, tool, error, status, +1 more
copy file inside authorized roots, refuse overwrite. Rename accepts a destination absolute path. [v1.0.0; permissions: none]
Inputs: source (required), destination (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Create a single directory within an authorized root. [v1.0.0; permissions: none]
Inputs: path (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
List immediate directory entries within authorized roots without following directory symlinks. [v1.0.0; permissions: none]
Inputs: path (required), limit. Returns: data, tool, error, status, +1 more
move file inside authorized roots, refuse overwrite. Rename accepts a destination absolute path. [v1.0.0; permissions: none]
Inputs: source (required), destination (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Open an authorized file with its default app. [v1.0.0; permissions: none]
Inputs: path (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Read a UTF-8 text file within authorized roots, maximum 1 MiB. [v1.0.0; permissions: none]
Inputs: path (required). Returns: data, tool, error, status, +1 more
rename file inside authorized roots, refuse overwrite. Rename accepts a destination absolute path. [v1.0.0; permissions: none]
Inputs: source (required), destination (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Search filenames recursively within authorized root, at most 10,000 visited entries. Does not access Raycast private search index. [v1.0.0; permissions: none]
Inputs: path (required), query (required), limit. Returns: data, tool, error, status, +1 more
Move a file to macOS Trash via public FileManager API; no permanent deletion. [v1.0.0; permissions: none]
Inputs: path (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Create UTF-8 text file; will not overwrite existing files. [v1.0.0; permissions: none]
Inputs: path (required), content (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
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]
Inputs: to (required), body (required), subject (required), _idempotencyKey (required), +1 more. Returns: data, tool, error, status, +1 more
Read one inbox message by numeric Mail ID; limited to current inbox scope. [v1.0.0; permissions: automation:Mail]
Inputs: id (required). Returns: data, tool, error, status, +1 more
Search subject substring in inbox messages via Mail scripting. Reads at most the most recent 500 inbox messages. [v1.0.0; permissions: automation:Mail]
Inputs: query (required), limit. Returns: data, tool, error, status, +1 more
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]
Inputs: to (required), body (required), subject (required), _idempotencyKey (required), +1 more. Returns: data, tool, error, status, +1 more
Control Music playback with fixed action play, pause, next, previous. [v1.0.0; permissions: automation:Music]
Inputs: action (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Play a track in the local Music library by database ID. [v1.0.0; permissions: automation:Music]
Inputs: id (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Search local Music library by track name; does not search streaming catalog. [v1.0.0; permissions: automation:Music]
Inputs: query (required), limit. Returns: data, tool, error, status, +1 more
Read Music playback state and current track, when present. [v1.0.0; permissions: automation:Music]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
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]
Inputs: url (required), http, timeoutMs. Returns: data, tool, error, status, +1 more
Append safely encoded plain text to an existing note. Locked notes may reject access. [v1.0.0; permissions: automation:Notes]
Inputs: id (required), text (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Create a note in the default Notes account; plain text is safely encoded as HTML. [v1.0.0; permissions: automation:Notes]
Inputs: text (required), title (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Read note body as HTML via native Notes scripting interface. [v1.0.0; permissions: automation:Notes]
Inputs: id (required). Returns: data, tool, error, status, +1 more
Search note titles in Notes via its public AppleScript dictionary. Returns IDs and titles, not private database contents. [v1.0.0; permissions: automation:Notes]
Inputs: query (required), limit. Returns: data, tool, error, status, +1 more
Set a reminder completion state and return saved record. [v1.0.0; permissions: reminders]
Inputs: id (required), completed (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Create a reminder; due dates require timezone. [v1.0.0; permissions: reminders]
Inputs: title (required), _idempotencyKey (required), due, notes, +4 more. Returns: data, tool, error, status, +1 more
Permanently delete a reminder with human approval. [v1.0.0; permissions: reminders]
Inputs: id (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
List EventKit reminder lists. [v1.0.0; permissions: reminders]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
Read reminders, optionally filtering list and completion; bounded result. [v1.0.0; permissions: reminders]
Inputs: limit, listId, completed. Returns: data, tool, error, status, +1 more
Update reminder fields by native ID. [v1.0.0; permissions: reminders]
Inputs: id (required), _idempotencyKey (required), due, notes, +5 more. Returns: data, tool, error, status, +1 more
Close a tab identified by window ID and one-based tab index. Prompts for human approval. [v1.0.0; permissions: automation:Safari]
Inputs: tabIndex (required), windowId (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Read open Safari windows and tabs, titles and URLs via Safari scripting. [v1.0.0; permissions: automation:Safari]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
Open one HTTP(S) URL in Safari. [v1.0.0; permissions: automation:Safari]
Inputs: url (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Discover names of user-installed Apple Shortcuts using the public shortcuts CLI. [v1.0.0; permissions: none]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
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]
Inputs: name (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Activate a running application by bundle ID. [v1.0.0; permissions: none]
Inputs: bundleId (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Capture full display or one window to PNG inside an authorized file root. Screen Recording permission required. [v1.0.0; permissions: screenRecording]
Inputs: outputPath (required), _idempotencyKey (required), windowId, _approvalId. Returns: data, tool, error, status, +1 more
Read frontmost focused window title and geometry via Accessibility. [v1.0.0; permissions: accessibility]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
Read frontmost application metadata using NSWorkspace. [v1.0.0; permissions: none]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
Read focused Accessibility element selected text. Does not use clipboard keystroke fallback. [v1.0.0; permissions: accessibility]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
List running regular applications. [v1.0.0; permissions: none]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
List visible window metadata; titles require Screen Recording permission on some macOS versions. [v1.0.0; permissions: screenRecording]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
Open an installed app by exact bundle ID; does not execute arbitrary binaries. [v1.0.0; permissions: none]
Inputs: bundleId (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Open an http or https URL in the default browser. Other URL schemes are forbidden. [v1.0.0; permissions: none]
Inputs: url (required), _idempotencyKey (required), _approvalId. Returns: data, tool, error, status, +1 more
Run one fixed read-only utility: disk_usage, battery, uptime. No command string or shell accepted. [v1.0.0; permissions: none]
Inputs: command (required). Returns: data, tool, error, status, +1 more
Move/resize the frontmost focused window using Accessibility. Does not implement arbitrary UI clicking. [v1.0.0; permissions: accessibility]
Inputs: x (required), y (required), width (required), height (required), +2 more. Returns: data, tool, error, status, +1 more
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]
Inputs: no named parameters. Returns: data, tool, error, status, +1 more
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]
Inputs: url (required), maxChars, timeoutMs. Returns: data, tool, error, status, +1 more
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]
Inputs: query (required), limit, provider, timeoutMs. Returns: data, tool, error, status, +1 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
