This secure MCP server provides Claude with safe access to macOS productivity apps—Reminders, Calendar, and Notes—through semantic tools, strict input validation, and template-based script generation for reliable automation.

How to use

You will interact with the MCP server through an MCP client. The server exposes app-specific tools that let you manage Reminders, Calendar events, and Notes in a structured, safe way. Use the appropriate tool for your task, for example creating a reminder, listing events within a date range, or creating a note with HTML content.

To perform actions, call the tools by name via your MCP client. Each tool expects specific inputs such as titles, dates, notes, locations, or body content. The server validates inputs at every stage, preventing unsafe or malformed commands from executing.

How to install

Prerequisites include a macOS device, and either Node.js 18+ or Bun. You also need a package manager such as pnpm (recommended) or npm.

Option 1: Binary Installation (Recommended) Install a pre-built binary on Apple Silicon devices.

# For Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/neverprepared/macos-ecosystem-mcp/releases/latest/download/macos-mcp-arm64 -o macos-mcp
chmod +x macos-mcp
sudo mv macos-mcp /usr/local/bin/

Note: Intel Macs can run via Rosetta 2 or install from source.

Option 2: Install from Source Clone the repository, install dependencies, and build.

git clone https://github.com/neverprepared/macos-ecosystem-mcp.git cd macos-ecosystem-mcp pnpm install pnpm build

## Configuration

Configure how you connect your MCP client to this server. You can use either Claude Code (CLI) or Claude Desktop to register and run the MCP server.

Claude Code (CLI) setup for binary installation:

{ "mcpServers": { "macos-ecosystem": { "command": "/usr/local/bin/macos-mcp" } } }

Claude Code (CLI) setup for source installation:

{ "mcpServers": { "macos-ecosystem": { "command": "/absolute/path/to/macos-ecosystem-mcp/start.sh" } } }

Verify the server is loaded by listing MCP servers from Claude Code.

claude mcp list

Should show "macos-ecosystem" in the list

## Environment variables

Copy the example environment file and customize values for logging, timeouts, and security validation.

cp .env.example .env

Available options:
- LOG_LEVEL: Logging verbosity: debug, info, warn, error (default: info)
- SCRIPT_TIMEOUT: Script execution timeout in milliseconds (default: 30000)
- ENABLE_SECURITY_VALIDATION: Enable security checks (default: true)

macOS permissions

On first use, you must grant automation permissions so the server can control Reminders, Calendar, and Notes.

Navigate to System Settings > Privacy & Security > Automation and allow access for the MCP server to control Reminders, Calendar, and Notes.

Usage examples

Create a reminder, find free time, create a note, and search reminders using natural language prompts that describe your intent.

Create a reminder "Review PR #123" in my Work list, due tomorrow at 2pm, high priority

Find me a 30-minute slot tomorrow between 9am and 5pm

Create a note titled "Meeting Notes - Q1 Planning" with the following content: [your content]

Development

Development workflows include testing, type checking, and running in development mode.

pnpm test              # Run once
pnpm test:watch        # Watch mode
pnpm test:coverage     # With coverage report

pnpm typecheck

pnpm dev

Security

Defense-in-depth security includes input validation, template-based generation, an AppleScript validator, an app whitelist, and timeout protections.

Architecture

The server is built with TypeScript and uses Zod for runtime validation, date-fns for date handling, run-applescript for AppleScript execution, and Vitest for testing.

Troubleshooting

If you encounter permission errors, grant automation permissions in macOS settings and restart the client. If scripts time out, increase SCRIPT_TIMEOUT in the environment file. Enable debug logs by setting LOG_LEVEL=debug.

Support

For issues or feature requests, open an issue on the project hosting platform.

Available tools

reminders_add

Create reminders with title, notes, due date, and priority.

reminders_list

List reminders with filtering by list and completion status.

reminders_complete

Mark reminders as completed.

reminders_search

Search reminders by keyword.

calendar_create_event

Create calendar events with full details (location, notes, alerts).

calendar_list_events

List events within a date range.

calendar_find_free_time

Find available time slots for scheduling.

calendar_update_event

Modify existing events.

calendar_delete_event

Delete events.

notes_create

Create notes with title and body (supports HTML).

notes_append

Append content to existing notes.

notes_search

Search notes by keyword.