mac_mcp/README.md

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 with account context and assignment metadata availability
reminders_list	List reminders, including assignment details or assignment hints for shared-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, current traffic speeds, and linked mesh node when available
deco_get_ipv4_status	Read WAN/LAN IPv4 status
deco_get_firmware	Read Deco model and firmware version
system_get_info	Get macOS version (sw_vers), hardware model, and SpeechAnalyzer availability
system_speech_api_status	Full check for Apple SpeechAnalyzer/SpeechTranscriber (macOS 26+)
codex_image_get_config_status	Show local Codex CLI image generation config
codex_image_generate	Generate an image with this Mac's Codex CLI and save it locally
gemini_image_get_config_status	Show Gemini image generation config without revealing the API key
gemini_image_generate	Generate an image with the Gemini API and save it locally
gemini_chrome_prompt_get_config_status	Show config for the Codex Chrome-skill Gemini image prompt builder
gemini_chrome_prompt_build	Build a ready-to-run Codex prompt for Gemini web-app image generation

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.

Reminder assignment data is exposed on reminders_list as an assignment object. Apple Reminders automation does not currently publish shared-list participant metadata directly, so the tool first checks for any native assignee field macOS exposes and then falls back to assignment hints embedded in the reminder title or notes, such as (Alicia) or Captured 2026-05-18, Alicia;.

macOS 26 note: This Mac is on macOS 26.5.2 (Mac16,10 M4) — so system_speech_api_status confirms SpeechAnalyzer/SpeechTranscriber is available. Apple's new engine beats Whisper Small 2.12% vs 3.74% WER per Inscribe benchmark (2026-07-13).

Setup

Requires macOS and Node.js 20 or newer.

npm install
npm run python:install
npm run check
npm run service:install

The service defaults to a same-Mac endpoint:

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

URL: http://<mac-lan-ip>:7331/mcp
Authorization: Bearer <MACMI...KEN>

Restart after changing .env:

npm run service:restart

For TP-Link Deco tools, install Python dependencies with npm run python:install, then set DECO_HOST, DECO_USERNAME=admin, DECO_PASSWORD, and optionally DECO_VERIFY_SSL=false in .env.

For Codex image generation, make sure the Mac is logged in with codex login. Generated files are saved to generated-images/ by default; override this with CODEX_IMAGE_OUTPUT_DIR. Set CODEX_IMAGE_MODEL or CODEX_IMAGE_TIMEOUT_MS or CODEX_CLI_PATH to the absolute codex path.

For Gemini image generation, set GEMINI_API_KEY in .env. Generated files are saved to generated-images/ by default; override this with GEMINI_IMAGE_OUTPUT_DIR. The Gemini image tool calls the Gemini API directly and does not expose browser navigation, page inspection, or screenshot tools.

For Gemini image generation through the signed-in Chrome web app, use gemini_chrome_prompt_build to create a ready-to-run Codex prompt. The MCP service does not control Chrome directly; the Chrome skill is only available inside an active Codex session. The generated prompt verifies the Chrome profile name is ReynaFamilyBot, opens only https://gemini.google.com/app, submits the image prompt, downloads the generated image, and copies it to generated-images/. Override the expected Chrome profile with GEMINI_CHROME_PROFILE_NAME and the output directory with GEMINI_CHROME_IMAGE_OUTPUT_DIR.

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

npm run check
npm run dev

The MCP transport follows the official TypeScript SDK Streamable HTTP server approach: Model Context Protocol TypeScript SDK.

Image generation

This server exposes Codex-backed and Gemini-backed image generation tools. Gemini image generation uses the Gemini API directly, not browser automation. Image Playground was tried and removed because the macOS app does not expose a scriptable prompt-to-file action through AppleScript or Shortcuts/App Intents.