Adolfo Reyna
136 lines
4.2 KiB
Markdown
136 lines
4.2 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 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 |
|
|
| `deco_get_config_status` | Show Deco connection config without revealing the password |
|
|
| `deco_get_overview` | Read TP-Link Deco overview stats and firmware |
|
|
| `deco_list_clients` | List online Deco clients and current traffic speeds |
|
|
| `deco_get_ipv4_status` | Read WAN/LAN IPv4 status |
|
|
| `deco_get_firmware` | Read Deco model and firmware version |
|
|
|
|
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 python: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 TP-Link Deco tools, install Python dependencies with `npm run
|
|
python:install`, then set `DECO_HOST`, `DECO_USERNAME`, `DECO_PASSWORD`, and
|
|
optionally `DECO_VERIFY_SSL=false` in `.env`.
|
|
|
|
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).
|