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 calendars and write capability
`calendar_list_events`	List events in an ISO-8601 time window
`calendar_create_event`	Create an event on a named writable 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.

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.

2.6 KiB Raw Blame History