MacMini MCP

A local Model Context Protocol server that exposes selected macOS app actions to an AI harness. It uses Apple's scripting interfaces through /usr/bin/osascript and stays on the local machine.

Available tools

Tool	Action
`notes_list`	Search notes; returns titles and metadata unless previews are explicitly requested
`notes_read`	Read a note by the ID returned by `notes_list`
`notes_create`	Create a plaintext-backed note
`calendar_list_calendars`	List calendar indexes, names, and write capability
`calendar_list_events`	List events in an ISO-8601 time window from the focused `Home` calendar
`calendar_create_event`	Create an event in the focused `Home` calendar
`reminders_list_lists`	List reminder lists
`reminders_list`	List reminders
`reminders_create`	Create a reminder
`contacts_search`	Search contact names and organizations without disclosing contact methods
`contacts_read`	Read phone and email details for one selected contact
`contacts_create`	Create a contact with optional email and phone details

There are no destructive tools in the initial server.

Calendar names can repeat across accounts. This server is focused on the event-rich Home calendar discovered during setup (calendarIndex: 2) and verifies the selected index is still named Home before operating on it. Calendar selector parameters remain available as advanced overrides.

Setup

Requires macOS and Node.js 20 or newer.

npm install
npm run check
npm run service:install

The service defaults to a same-Mac endpoint:

http://127.0.0.1:7331/mcp

Health check:

curl -s http://127.0.0.1:7331/health

launchd runs node --watch src/http.js, so edits to the server or imported modules cause it to restart automatically while the agent remains installed. After changing installed dependencies or service configuration, run:

npm install
npm run service:install

Operational commands:

npm run service:status
npm run service:restart
npm run service:uninstall

Service logs are stored in .logs/.

Harness configuration

For a harness that supports Streamable HTTP, configure the local MCP URL as http://127.0.0.1:7331/mcp.

For a trusted local-network harness such as a Raspberry Pi, set MACMINI_MCP_HOST in .env to the Mac's LAN IP and set a strong MACMINI_MCP_TOKEN. Then configure the remote MCP client with:

URL: http://<mac-lan-ip>:7331/mcp
Authorization: Bearer <MACMINI_MCP_TOKEN>

Restart after changing .env:

npm run service:restart

For a harness that launches stdio servers, use:

{
  "mcpServers": {
    "macmini": {
      "command": "/Users/adolforeyna/.nvm/versions/node/v22.22.0/bin/node",
      "args": ["/Users/adolforeyna/Projects/MacMiniMCP/src/stdio.js"]
    }
  }
}

Permissions and security

On first use of a Notes, Calendar, Reminders, or Contacts tool, macOS may ask for Automation access for Node. Permit only the applications you want the server to control under System Settings > Privacy & Security > Automation.

The HTTP service binds to 127.0.0.1 by default. When configured to bind to a LAN address, it refuses to start without MACMINI_MCP_TOKEN; clients must send Authorization: Bearer <token>. This is HTTP bearer authentication on your local network, not encrypted transport. Use it only on a trusted LAN or put it behind a private encrypted network such as a VPN.

Development

npm run check
npm run dev

The MCP transport follows the official TypeScript SDK Streamable HTTP server approach: Model Context Protocol TypeScript SDK.

3.7 KiB Raw Blame History