# Mac Shortcuts — read your Mac from any agent

Lets AI agents inspect your macOS Calendar, Reminders, Notes, and Contacts through Apple Shortcuts. Operates locally without external cloud accounts.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 14
- Author: Dominic-DK
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Dominic-DK/mac-shortcuts-mcp
- Updated: 2026-09-21
- HTML: https://affpapa.org/en/nevibecode/mcp/mac-shortcuts-read-your-mac-from-any-agent

## What it does

AI coding assistants lack native operating system permissions to query Apple applications directly. This server delegates read operations to `Shortcuts.app`, which already has those access rights, and returns clean text back to the model. Retrieved contents are marked explicitly as data rather than instructions, preventing prompt injections hidden inside personal notes.

Built-in tools cover calendar events, task lists, contacts by query, clipboard text, local coordinates, weather, and active media playback. The package also embeds `action-catalog.json`, detailing 539 action schemas extracted from the macOS 27 registry. Because `mac_run_shortcut` can trigger custom local shortcuts that send messages or modify files, the environment does not enforce a strict read-only sandbox.

Getting started requires running `npx -y mac-shortcuts-mcp setup` to sign and add XML property lists inside the Shortcuts app. The tool runs on macOS only. A locked display handles calls normally, but Mac system sleep halts background execution entirely. When your Mac sleeps, the server cannot respond.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mac-shortcuts-mcp -- npx -y mac-shortcuts-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add mac-shortcuts-read-your-mac-from-any-agent -- npx -y mac-shortcuts-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mac-shortcuts-read-your-mac-from-any-agent": {
            "command": "npx",
            "args": [
                "-y",
                "mac-shortcuts-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mac-shortcuts-read-your-mac-from-any-agent": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "mac-shortcuts-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mac-shortcuts-read-your-mac-from-any-agent npx -y mac-shortcuts-mcp
```

## When to use it
- check upcoming calendar appointments for the week
- pull search matches and body text from Apple Notes
- retrieve phone numbers and email details from Contacts
- inspect current clipboard content and device battery status
- verify parameter keys across 539 macOS Shortcuts actions

## Example prompts
- Show me all events scheduled on my calendar for the next three days.
- Find the note regarding apartment repairs and print its text.
- Look up Alex in my contacts and give me his phone number.

## Similar
- [Reactive Resume](https://affpapa.org/en/nevibecode/mcp/reactive-resume.md) — MCP server · ★ 44908
- [screenpipe](https://affpapa.org/en/nevibecode/mcp/screenpipe.md) — MCP server · ★ 22082
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12826
- [kaneo](https://affpapa.org/en/nevibecode/mcp/kaneo.md) — MCP server · ★ 9623
- [Mindwtr](https://affpapa.org/en/nevibecode/mcp/mindwtr.md) — MCP server · ★ 2330
- [Azure DevOps (ADO)](https://affpapa.org/en/nevibecode/mcp/azure-devops-ado.md) — MCP server · ★ 2071

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md