macOS Companion MCP Server
Provides tools for interacting with Apple's native macOS applications, including Calendar, Reminders, Notes, and iMessage.
Allows sending iMessages programmatically through the native macOS messaging service.
Offers system administration tools for macOS, including health audits, battery monitoring, storage scans, and process management.
Enables retrieval of open Safari tabs and browsing context.
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 Companion MCP Server run a system health check"
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.
macOS Companion MCP Server 🍏
Native macOS Companion MCP server for AI agents: system control, clipboard management, desktop notifications, audio devices, and workspace automation.
🌐 Live Documentation & Web Portal: https://macos.builditwithai.xyz
⚡ Quickstart
# 1-Line Universal Installer (Auto-configures Claude Desktop, Cursor, Claude Code, Antigravity, VS Code, Zed, Windsurf)
curl -fsSL "https://macos.builditwithai.xyz/install" | bash
# Or run directly via your preferred runtime:
uvx macos-companion-mcp
npx -y @surendranb/macos-companion-mcpRelated MCP server: Mac MCP
🤖 Client Setup
A. Claude Code (CLI)
claude mcp add macos-companion -- npx -y @surendranb/macos-companion-mcpB. Cursor & Google Antigravity (mcp.json)
{
"mcpServers": {
"macos-companion": {
"command": "npx",
"args": ["-y", "@surendranb/macos-companion-mcp"]
}
}
}C. Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"macos-companion": {
"command": "npx",
"args": ["-y", "@surendranb/macos-companion-mcp"]
}
}
}D. Python UVX Alternative
{
"mcpServers": {
"macos-companion": {
"command": "uvx",
"args": ["macos-companion-mcp"]
}
}
}🛠️ Tools & Capabilities
Tool Name | Parameters | Description | Return Type |
|
| Dispatches native macOS desktop notifications with alert sounds. |
|
| (none) | Reads current plain text contents from the system clipboard. |
|
|
| Writes text directly to the macOS system clipboard. |
|
| (none) | Lists available audio input/output devices and current volume level. |
|
|
| Adjusts macOS system output volume. |
|
| (none) | Returns the active, focused desktop application name and bundle ID. |
|
| (none) | Lists visible application window titles and coordinates. |
|
| (none) | Returns connected monitor resolutions, scaling, and display arrangements. |
|
|
| Opens a URL in the user's default browser or specific application. |
|
|
| Runs sandboxed AppleScript / JXA automation commands safely. |
|
|
| Loads macOS automation playbooks dynamically from GitHub. |
|
| (none) | Lists all available macOS automation skills. |
|
🔒 Telemetry & Privacy
This package collects anonymous, non-PII diagnostic telemetry (command executions, latency, error codes) to improve tool reliability. No clipboard contents, notification text, personal data, source code, or environment variables are ever collected or stored.
You can opt out anytime by setting either of the following environment variables:
export DO_NOT_TRACK=1
# or
export MCP_TELEMETRY_OPT_OUT=1📄 License
MIT License. See LICENSE for details.
Available Tools
40 toolscapture_audioA
Records an audio clip via microphone and saves to a temp WAV file. Returns file path, duration, and sample rate.
Inputs: duration.
capture_camera_snapshotA
Takes a photo using the built-in camera via imagesnap. Returns JPEG as base64 data URL. Use: ambient light sensing, health PPG read, presence detection.
Inputs: delay, quality.
complete_reminderB
Marks a reminder as completed
Inputs: id (required).
create_calendar_eventA
Creates a new event in Apple Calendar (using accli)
Inputs: end (required), start (required), summary (required), calendar (required), +2 more.
create_noteA
Creates a new note in Apple Notes
Inputs: body (required), title (required), folder.
create_reminderB
Creates a new reminder in Apple Reminders
Inputs: title (required), due, list, notes.
get_ambient_noiseA
Records a short audio sample via microphone and measures ambient noise level in decibels. Returns average dB, peak dB, and classification (quiet/moderate/loud).
Inputs: duration.
get_battery_healthA
Detailed battery status: cycle count, max capacity, condition
Inputs: no named parameters.
get_calendar_eventsB
Fetches calendar events for a given time range (using accli)
Inputs: to (required), from (required).
get_disk_usageB
Returns local disk usage statistics
Inputs: no named parameters.
get_music_stateA
Returns the current playback state and active track metadata in Apple Music
Inputs: no named parameters.
get_noteC
Retrieves the body text of a note by title or ID
Inputs: id (required).
get_podcast_transcriptA
Retrieves the full transcript for an episode from the local Apple Podcasts TTML cache. Returns speaker-attributed text with timestamps. Requires the episode to have been opened/played at least once so the transcript file was cached locally.
Inputs: transcriptId (required), includeTimestamps.
get_process_listA
Lists active running processes with resource usage
Inputs: no named parameters.
get_recent_podcast_episodesA
Lists podcast episodes from MTLibrary.sqlite, optionally filtered by release date range and/or title query. Returns pubDate, podcastTitle, title, playhead, duration, playState, transcriptId (path fragment), episodeId (Apple store track id). Pass a title to open_podcast_episode, and transcriptId to get_podcast_transcript once cached.
Inputs: limit, query, toDate, fromDate, +1 more.
get_remindersA
Fetches active reminders from Apple Reminders
Inputs: list.
get_safari_tabsA
Lists all open tab URLs and titles in Safari
Inputs: no named parameters.
get_startup_itemsA
Lists macOS login items and LaunchAgents
Inputs: no named parameters.
get_storage_scanB
Deep storage scan: home directory sizes, caches, and local snapshots
Inputs: no named parameters.
get_system_statsA
Gets current CPU load, memory pressure, battery metrics, thermal level, and hung processes
Inputs: no named parameters.
get_unread_emailsA
Fetches recent unread email details from Apple Mail
Inputs: no named parameters.
kill_processB
Kills a process by PID or name
Inputs: pid, name.
list_calendarsA
Lists all available calendar names in the Apple Calendar app
Inputs: no named parameters.
list_notesA
Lists titles, IDs, and folders of notes in Apple Notes
Inputs: no named parameters.
list_shortcutsA
Lists all Siri/Apple Shortcuts configured on the system
Inputs: no named parameters.
open_podcast_episodeA
Searches Apple Podcasts for an episode title (from get_recent_podcast_episodes) and opens its episode page. Verified UI flow: Cmd+F, clipboard-paste the title (keystroke typing corrupts punctuation), open the top search result. Use before play_podcast_episode. The title should be fairly exact — the top search result is what gets opened.
Inputs: title (required).
open_urlA
Opens a URL in the default browser
Inputs: url (required).
pause_podcast_episodeA
Pauses Apple Podcasts playback via the Controls menu bar item. Note: the MTLibrary play_state column is unreliable (stays 1 while paused) — use the playhead field of get_recent_podcast_episodes to verify pause.
Inputs: no named parameters.
play_pause_musicA
Toggles playback state of Apple Music
Inputs: no named parameters.
play_playlistA
Plays a specific Apple Music playlist by name
Inputs: name (required).
play_podcast_episodeA
Plays the currently open episode page in Apple Podcasts (AX-discovers the play pill — position varies per page, so it is never hardcoded — and clicks it), then polls the TTML cache for up to ~15s for the transcript download. Returns the cached transcript path and transcriptId for get_podcast_transcript. Requires open_podcast_episode to have been called first.
Inputs: no named parameters.
restart_serviceB
Restarts a macOS launchd service using launchctl
Inputs: service (required).
run_disk_cleanupC
Safely prunes cache folders and empties trash to free up space
Inputs: targets (required).
run_health_auditA
Comprehensive health audit: compute, memory, storage, battery, SSD wear, startup items
Inputs: no named parameters.
run_shortcutB
Runs an Apple/Siri Shortcut by name
Inputs: name (required), input.
send_emailB
Composes and sends an email via Apple Mail
Inputs: to (required), body (required), subject (required).
send_imessageB
Sends an iMessage/SMS via Messages app
Inputs: to (required), message (required).
set_music_volumeA
Sets Apple Music volume (0 to 100)
Inputs: volume (required).
skip_music_trackA
Skips to the next or previous track in Apple Music
Inputs: direction (required).
update_noteA
Appends content to an existing note in Apple Notes
Inputs: id (required), content (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Most tools target distinct apps and actions, but there is overlap among system monitoring tools (get_system_stats, get_battery_health, run_health_audit) and storage tools (get_disk_usage, get_storage_scan) that could cause misselection without careful reading.
The naming largely follows verb_noun snake_case (list_calendars, create_reminder), with minor deviations like play_pause_music (verb_verb) and get_storage_scan (noun-heavy). Overall predictable.
40 tools is excessive for a single server, even with broad macOS scope. Many tools could be split into separate domain-specific servers (calendar, system, podcasts). This makes the surface heavy to navigate.
Core operations exist for most apps (create, read, list), but lifecycle coverage is incomplete: Calendar/Reminders/Notes lack delete, Music lacks queue control, Mail lacks folder/search operations. The podcast tools are unusually thorough, but other areas feel thin.
Maintenance
Related MCP Connectors
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
An MCP connector that lets your AI agents ask you questions, request permission approvals, and send alerts as push notifications to your phone and mac notch, so you can unblock and approve your agents from anywhere.
Related MCP Servers
- AlicenseBqualityDmaintenanceA macOS MCP server that provides AI agents with secure access to Calendar, Reminders, Notes, and Health data via native Apple APIs.3023MIT
- AlicenseNot gradedqualityAmaintenanceOpen-source, local macOS MCP server for AI agents. Automate background Safari/Chrome tabs, native apps, files and shell with scoped permissions, optional approvals and delegated coding agents.97MIT
- AlicenseBqualityDmaintenanceMCP server that enables AI to fully control macOS — mouse, keyboard, terminal, screenshots, window management, UI element detection, and provides AI-optimized information reporting.3630 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnterprise-grade macOS MCP server that gives AI agents eyes, hands, and a terminal, enabling screen capture, mouse/keyboard control, shell commands, and file operations.-