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

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

The service endpoint is:

```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 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, 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

```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).