mcps-for-macos

A collection of MCP servers (Model Context Protocol) for macOS automation. Each server wraps an app or system function via AppleScript or the command line and exposes it as tools that an AI application (Claude Desktop, Claude Code) can call.

Shared helpers (AppleScript execution including escaping, command execution) live in packages/common and are used by the servers as @mcps/common.

What is an MCP server?

MCP is an open standard through which AI applications (the host) talk to external tools and data. A server provides capabilities (tools) and knows nothing about AI itself. Communication via JSON-RPC 2.0, here via stdio (local process). Registering means: telling the host how to start the server. The host starts it as a subprocess at every session start, queries its tools, and makes them available to the AI.

Related MCP server: macos-mcp-tools

Installation

npm install

A single npm install in the root directory is enough for all servers (npm workspaces). No build step: pure ESM JavaScript, Node >= 18.

Registering

Each server is registered individually because each is its own process. Paths must be given as absolute paths; <REPO> stands for the path to this repo.

Claude Code

# global in allen Projekten (empfohlen für Systemwerkzeuge)
claude mcp add apple-calendar --scope user -- node <REPO>/packages/apple-calendar/src/index.js
claude mcp add apple-mail  --scope user -- node <REPO>/packages/apple-mail/src/index.js
claude mcp add money-money --scope user -- node <REPO>/packages/money-money/src/index.js
claude mcp add spotlight   --scope user -- node <REPO>/packages/spotlight/src/index.js

Without --scope user, the registration only applies to the current project. Check and remove:

claude mcp list
claude mcp remove spotlight

Claude Desktop

In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-calendar": { "command": "node", "args": ["<REPO>/packages/apple-calendar/src/index.js"] },
    "apple-mail":  { "command": "node", "args": ["<REPO>/packages/apple-mail/src/index.js"] },
    "money-money": { "command": "node", "args": ["<REPO>/packages/money-money/src/index.js"] },
    "spotlight":   { "command": "node", "args": ["<REPO>/packages/spotlight/src/index.js"] }
  }
}

macOS permissions

• Automation. On first access, macOS asks for automation access to Mail, Calendar, or MoneyMoney. Allow it once.

• Full Disk Access. Protected locations (e.g. ~/Library/Mail) only return results with Full Disk Access for the executing process (System Settings → Privacy & Security → Full Disk Access).

Test locally

Click through each server individually with the MCP Inspector:

npm run inspect -w @mcps/spotlight

License

MIT