# 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.

```sh
npm install
npm run check
npm run service:install
```

The service defaults to a same-Mac endpoint:

```text
http://127.0.0.1:7331/mcp
```

Health check:

```sh
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:

```sh
npm install
npm run service:install
```

Operational commands:

```sh
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:

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

Restart after changing `.env`:

```sh
npm run service:restart
```

For a harness that launches stdio servers, use:

```json
{
  "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

```sh
npm run check
npm run dev
```

The MCP transport follows the official TypeScript SDK Streamable HTTP server
approach: [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).