Adolfo Reyna
108 lines
3.0 KiB
Markdown
108 lines
3.0 KiB
Markdown
# 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).
|