Skip to main content
Glama
macOS Companion MCP Server

macOS Companion MCP Server

by surendranb

macOS Companion MCP Server 🍏

Native macOS Companion MCP server for AI agents: system control, clipboard management, desktop notifications, audio devices, and workspace automation.

CI npm version PyPI version OpenSSF Scorecard License: MIT

🌐 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-mcp


Related MCP server: Mac MCP

🤖 Client Setup

A. Claude Code (CLI)

claude mcp add macos-companion -- npx -y @surendranb/macos-companion-mcp

B. 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

notify

title (string), message (string), sound (optional)

Dispatches native macOS desktop notifications with alert sounds.

JSON

clipboard_read

(none)

Reads current plain text contents from the system clipboard.

string

clipboard_write

text (string)

Writes text directly to the macOS system clipboard.

JSON

get_audio_devices

(none)

Lists available audio input/output devices and current volume level.

JSON

set_volume

volume (0-100)

Adjusts macOS system output volume.

JSON

get_frontmost_app

(none)

Returns the active, focused desktop application name and bundle ID.

JSON

get_open_windows

(none)

Lists visible application window titles and coordinates.

JSON

get_displays

(none)

Returns connected monitor resolutions, scaling, and display arrangements.

JSON

open_url

url (string)

Opens a URL in the user's default browser or specific application.

JSON

execute_applescript

script (string)

Runs sandboxed AppleScript / JXA automation commands safely.

JSON

skill_read

skill_name (string)

Loads macOS automation playbooks dynamically from GitHub.

Markdown

skills_list

(none)

Lists all available macOS automation skills.

JSON


🔒 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 tools
capture_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

    B3.3/5.0

    Scored across 40 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Open-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.
      97
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server that enables AI to fully control macOS — mouse, keyboard, terminal, screenshots, window management, UI element detection, and provides AI-optimized information reporting.
      36
      30 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enterprise-grade macOS MCP server that gives AI agents eyes, hands, and a terminal, enabling screen capture, mouse/keyboard control, shell commands, and file operations.
      -