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 note titles and plaintext previews
`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

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 endpoint is:

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 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, or Reminders 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. To require bearer authentication even locally, create .env from .env.example and set MACMINI_MCP_TOKEN; clients must then send Authorization: Bearer <token>. Do not bind to a non-loopback address without enabling authentication and reviewing the tools first.

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.0 KiB Raw Blame History