macOS MCP Server

Website: macos-mcp.builditwithai.xyz · npm: @surendranb/macos-companion-mcp · Studio: BuildItWithAI

What is this?

macOS MCP Server (npm package: @surendranb/macos-companion-mcp) is a local Model Context Protocol server that gives AI agents read/write access to your Mac. It exposes 40 MCP tools for Apple Calendar, Apple Notes, Apple Reminders, Apple Mail, iMessage, Apple Music, Apple Podcasts, Safari, Siri Shortcuts, camera, microphone, and system monitoring — all running locally over stdio, with no cloud, no API keys, no data leaving your machine.

It is the most direct way to give an AI assistant hands on a Mac: agents can check your calendar before scheduling, summarize unread mail, create reminders, control music, fetch podcast transcripts, and run health checks on your system.

Works with: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, OpenCode, and any other MCP-compatible client.

Why a local macOS MCP server

Web agents only see the internet. A local agent should be able to check your calendar before it schedules something, read your unread mail, glance at the battery before you leave the house, and pull the transcript of the podcast episode you're listening to. There's no public API for any of that — it's all AppleScript and CLI wrappers behind the curtain. This server bundles them into one clean MCP surface, so your agent talks to your Mac the way you do.

Install

Get started in 60 seconds:

npm install -g @surendranb/macos-companion-mcp

Or run it on demand — add this to any MCP client's config:

{
  "mcpServers": {
    "macos": {
      "command": "npx",
      "args": ["-y", "@surendranb/macos-companion-mcp"]
    }
  }
}

That's it. The server announces macOS MCP Server running on stdio and your client picks up all 40 tools automatically. It auto-detects the calling client (Claude Code, Cursor, Gemini CLI, Windsurf, VS Code) and logs it in telemetry.

What you get — all 40 tools

Apple Calendar & Reminders (6)

| tool | what it does | |------|-------------| | list_calendars | Lists your calendars | | get_calendar_events | Events in a date range | | create_calendar_event | Creates a new event | | get_reminders | Active reminders from any list | | create_reminder | New reminder with due date | | complete_reminder | Marks a reminder done |

Apple Mail & iMessage (3)

| tool | what it does | |------|-------------| | get_unread_emails | Unread Mail.app messages with details | | send_email | Sends mail from your account | | send_imessage | Texts via the Messages app |

Apple Notes (4)

| tool | what it does | |------|-------------| | list_notes | All Apple Notes titles and IDs | | get_note | Full note body by ID | | create_note | New note in a folder | | update_note | Appends content to a note |

Apple Music (5)

| tool | what it does | |------|-------------| | get_music_state | Current track + playback position | | play_playlist | Starts a playlist by name | | play_pause_music | Toggles playback | | skip_music_track | Next/previous track | | set_music_volume | Volume 0–100 |

Apple Podcasts (5)

| tool | what it does | |------|-------------| | get_recent_podcast_episodes | Episodes, filterable by release date and title | | open_podcast_episode | Opens an episode in the Podcasts app | | play_podcast_episode | Plays the episode and waits for its transcript | | get_podcast_transcript | Full transcript from the local TTML cache | | pause_podcast_episode | Pauses playback |

System monitoring & control (10)

| tool | what it does | |------|-------------| | get_system_stats | CPU, memory, thermal, hung processes | | get_process_list | Processes with resource usage | | kill_process | Kills a process by PID or name | | restart_service | Restarts a launchd service | | get_battery_health | Cycle count, max capacity, condition | | get_disk_usage | Disk usage statistics | | get_storage_scan | Deep scan of home directory | | get_startup_items | Login items + LaunchAgents | | run_health_audit | Full health audit | | run_disk_cleanup | Prunes caches + empties trash |

Utilities (4)

| tool | what it does | |------|-------------| | open_url | Opens a URL in the default browser | | get_safari_tabs | Open Safari tabs with URLs | | list_shortcuts | Siri Shortcuts on the system | | run_shortcut | Runs a shortcut with optional input |

Sensing (3)

| tool | what it does | |------|-------------| | capture_camera_snapshot | Photo via built-in camera (base64 JPEG) | | get_ambient_noise | Ambient noise level in dB | | capture_audio | Records a WAV clip (up to 30s) |

Podcast transcripts — how it works

Apple Podcasts stores full episode transcripts locally as TTML files, but only after an episode has actually played. The verified end-to-end pipeline:

1. get_recent_podcast_episodes — query the local Podcasts library by date range / title. Note the transcriptId for the episode you want.
2. open_podcast_episode — searches the Podcasts UI and opens the episode page.
3. play_podcast_episode — clicks the play pill and polls the TTML cache until the transcript file appears (usually 2–8 seconds).
4. get_podcast_transcript — returns the full transcript. Already cached? It's instant.
5. pause_podcast_episode — stops playback.

Transcripts live in ~/Library/Group Containers/243LU875E5.groups.com.apple.podcasts/.../TTML/. The cache holds only the most recent ~8 episodes — replay an older one to re-download it.

Configuration & permissions

There's no configuration file. Just make sure macOS can reach the apps:

• Mail / Calendar / Notes / Reminders / Messages — launch each app once so Apple's automation permissions are granted. The server warms apps at startup so the first call isn't a 30-second cold launch.
• Camera / Microphone — System Settings → Privacy & Security → Camera/Microphone → allow Terminal (or whichever process runs the server).
• Full Disk Access — needed only for system-level storage scans.

Architecture

• Language: TypeScript, MCP 2.0 SDK (@modelcontextprotocol/server)
• Transport: stdio only — no HTTP server, no network
• Integration layer: AppleScript (osascript), native CLIs (accli, imagesnap, launchctl, shortcuts), and direct reads of Apple's local databases (Podcasts)
• Layout: tool schemas and handlers in src/index.ts; startup telemetry in src/telemetry.ts
• Publishing: GitHub Actions (release.yml) publishes to npm on release

Development

npm ci
npm run build          # tsc → dist/
node dist/index.js     # run the server on stdio
npm test               # smoke suite: 19 end-to-end checks against a live server

FAQ

Is this safe? Does it send my data anywhere? It runs entirely locally over stdio. No cloud services, no API keys, no telemetry beyond an anonymous server-start event. All automation goes through Apple's own permission system.

Does it work on Apple Silicon / macOS Sequoia / Sonoma? Yes. It uses AppleScript and Apple's CLIs, which work across Intel and Apple Silicon Macs.

Why does the first calendar call feel slow? The server pre-warms Calendar, Mail, Notes, and Reminders at startup so permissions are in place and apps are not launched cold on first use.

Do I need to install anything else? Only Node.js 18+. Camera tools use imagesnap (Homebrew) and audio tools use sox/ffmpeg if you want those specific tools.

Is there an HTTP version? No — stdio only by design. It keeps everything local and is compatible with every MCP client.

Links

• Website: https://macos-mcp.builditwithai.xyz
• npm: https://www.npmjs.com/package/@surendranb/macos-companion-mcp
• Studio: https://builditwithai.xyz
• Issues: https://github.com/surendranb/macos-mcp/issues

License

MIT — Surendran Balachandran, 2026. Built at BuildItWithAI Studio.

Prior art

This project builds on patterns from DesktopCommanderMCP (terminal + file MCP server) and the GA4 MCP distribution playbook.