使用说明

macMCP

Standalone Swift MCP server exposing macOS-native tools via stdio. 51 tools across 13 services. No external dependencies.

Tools

Calendar

Tool	Description
`calendars_list`	List all calendars
`calendars_list_events`	List events within a date range
`calendars_create_event`	Create a new event

Contacts

Tool	Description
`contacts_list`	Search or list contacts
`contacts_get`	Get a contact by identifier
`contacts_create`	Create a new contact
`contacts_update`	Update an existing contact
`contacts_delete`	Delete a contact
`contacts_list_groups`	List all contact groups
`contacts_create_group`	Create a contact group
`contacts_add_to_group`	Add a contact to a group
`contacts_remove_from_group`	Remove a contact from a group
`contacts_search_by_phone`	Search contacts by phone number

Reminders

Tool	Description
`reminders_list`	List reminders, optionally filtered by list
`reminders_create`	Create a new reminder
`reminders_complete`	Mark a reminder as complete

Location

Tool	Description
`location_get_current`	Get current coordinates
`location_geocode`	Address to coordinates
`location_reverse_geocode`	Coordinates to address

Maps

Tool	Description
`maps_search`	Search for places or addresses
`maps_open`	Open a location in Apple Maps
`maps_get_directions`	Get directions URL between two points

Capture

Tool	Description
`capture_screenshot`	Take a screenshot
`capture_audio`	Record audio from default input

Mail

Tool	Description
`mail_list_accounts`	List configured mail accounts
`mail_list_mailboxes`	List mailboxes for an account
`mail_get_emails`	Get emails from a mailbox
`mail_get_email`	Get a single email with full body
`mail_search`	Search by subject or sender
`mail_send`	Send an email
`mail_create_draft`	Create an email draft (does not send)
`mail_move`	Move an email to another mailbox
`mail_move_to_junk`	Move an email to its own account's Junk mailbox (bounded: no other destination, no mail_mailboxes needed)
`mail_mark_reviewed`	Record a triage verdict in macMCP's own local cache, without touching Mail
`mail_clear_scan_cache`	Delete entries from that local cache
`mail_mark_read`	Mark as read/unread
`mail_get_source`	Get a message's raw RFC 822 source
`mail_save_attachment`	Save an attachment to disk

Messages

Tool	Description
`messages_list_chats`	List recent conversations
`messages_get_chat`	Get messages from a chat, including image attachments
`messages_search`	Search messages by text and/or contact, including image attachments
`messages_send`	Send an iMessage (text, reliable; an image, verified NOT reliable on this VM -- see CLAUDE.md), confirmed against chat.db rather than just that the request didn't error
`messages_save_attachment`	Save an image attachment to disk

Shortcuts

Tool	Description
`shortcuts_list`	List available shortcuts
`shortcuts_run`	Run a shortcut by name

Utilities

Tool	Description
`utilities_play_sound`	Play an audio file

Weather

Tool	Description
`weather_current`	Current conditions for a location
`weather_forecast`	Daily forecast
`weather_hourly`	Hourly forecast

Web

Tool	Description
`web_fetch`	Fetch an http/https URL (GET, 1 MB cap)

System

Tool	Description
`permissions_check`	Report the state of every macOS permission these tools need

Requirements

macOS 13+
Swift 5.9+
No external dependencies (system frameworks only)

Permissions

Grant these in System Settings > Privacy & Security as needed:

Contacts -- Contacts access
Calendar -- Calendars access
Reminders -- Reminders access
Location -- Location Services (on first use, macOS will prompt to allow; click Allow)
Messages -- Full Disk Access (reads chat.db directly, for messages_list_chats/messages_get_chat/messages_search) and Automation permission for Messages.app (messages_send, which drives it via AppleScript)
Mail -- Automation permission for Mail.app (uses JXA)

Build & Install

swift build              # debug
swift test               # unit tests (hermetic: no Mail.app, no network)
./build.sh               # release, codesigned, installs to ~/.local/bin, registers with Relay

build.sh installs the binary to ~/.local/bin/macmcp and registers it with Relay (if installed).

Code signing

Builds run codesign with hardened runtime. The first Developer ID Application cert in your login keychain is picked automatically; if none exists, the build falls back to ad-hoc signing. Pin a specific cert with RELAY_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" ./build.sh.

When signed with a stable Developer ID, macOS TCC keys permission grants off the bundle's designated requirement — so Contacts/Calendar/Reminders/Location prompts persist across rebuilds. Ad-hoc builds re-prompt every rebuild because TCC keys off the cdhash, which changes with every compile.

Configuration

With Relay (recommended)

build.sh handles registration automatically. To register manually:

relay mcp register --name macMCP --command ~/.local/bin/macmcp

Standalone

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "macmcp": {
      "command": "~/.local/bin/macmcp"
    }
  }
}

Related Projects

macMCP is part of a set of projects that combine to give LLMs secure access to macOS. Each works independently, but together they form a complete stack: Eve provides the LLM chat interface, Relay handles orchestration and security, and macMCP exposes native macOS capabilities. Register macMCP with Relay, and any MCP client (including Eve) gains access to its 50 tools -- scoped by per-token permissions so different projects can have different access levels.

Relay -- MCP orchestrator for macOS. macMCP self-registers with Relay via relay mcp register, and Relay proxies its tools through a single token-authenticated connection with per-tool permissions.
fsMCP -- Cross-platform file system MCP server (read, write, edit, glob, grep, bash). Complements macMCP's macOS-native tools with file manipulation capabilities.
Eve -- Multi-provider LLM web interface with projects, file editing, and terminal. When both Eve and macMCP register with Relay, LLM sessions gain access to macOS-native tools.
relayLLM -- LLM engine service.
relayScheduler -- Task scheduler for automated LLM prompts.

Acknowledgements

Special thanks to mattt/iMCP for the inspiration.