apple-tools-mcp

An MCP (Model Context Protocol) server for Apple Mail, Messages, Calendar, and Contacts on macOS. Search them in plain language, send mail and messages, and create, edit, or remove calendar events and contacts. It talks to any MCP client over stdio, or over HTTP with a bearer token. Plain-language search is retrieval-augmented: your mail, messages, and calendar events are embedded on your Mac and kept in a local LanceDB vector database (see How search works). The embeddings and the write bridge stay on your Mac.

How search works

Search runs against a local vector index, not a cloud service.

• Embedding model: Xenova/all-MiniLM-L6-v2, a 384-dimension sentence-embedding model (mean pooling, normalized), run on your Mac with Transformers.js. The model files are downloaded from Hugging Face the first time the model loads and cached after that. Your mail, messages, and events are never sent anywhere to be embedded.

• Vector database: LanceDB, embedded in the process (no server), stored in ~/.apple-tools-mcp/vector-index/ with three tables: emails, messages, and calendar.

• What is indexed:

  • Mail: every .emlx file under ~/Library/Mail, including partly downloaded ones. The embedded text is From, To, Subject, and the start of the body (1,000 characters in all).

  • Messages: iMessage and SMS from ~/Library/Messages/chat.db, including text that macOS stores only in the rich-text attributedBody field. The embedded text is the sender and the message (500 characters).

  • Calendar: events from Calendar's Calendar.sqlitedb. The embedded text is title, calendar, location, and notes (500 characters).

  • Contacts are not embedded. The contact tools and name matching read the Contacts (AddressBook) database directly.

• At query time: the question is embedded with the same model. Up to three variants of it (the original, one with time words removed, and one with a common synonym swapped in) each run a nearest-neighbour search. The result lists are merged with Reciprocal Rank Fusion (k = 60), then re-ranked by 70% vector similarity and 30% keyword match. If nothing comes back, one broader query is tried. smart_search chooses which tables to search from the question.

• Not from the index: mail_find, mail_links, calendar_date, calendar_free_time, the contact tools, and every write tool read Mail, Calendar, Contacts, or Messages live, so they work while the index is rebuilding.

The indexer (below) refreshes the index incrementally, every 5 minutes by default. The search tools return matching items for your MCP client's model to read and answer from.

Related MCP server: MCP Apple Notes

Requirements

• macOS

• Node.js 18 or later

• The permissions below, on the Mac that holds the Mail, Messages, Calendar, and Contacts data

Setup

1. Install

npm install -g apple-tools-mcp

Or from source:

git clone https://github.com/sfls1397/Apple-Tools-MCP.git
cd Apple-Tools-MCP
npm install

A global install uses npx in the client config below. A clone uses node and the full path to index.js.

After you install or upgrade, run the permissions command in the next section. npm install only prints a reminder. It cannot click Allow for you.

2. Permissions

Two grants, and they do different jobs.

Full Disk Access lets the server read the Mail, Messages, Calendar, and Contacts databases.

Automation lets it send mail, send messages, and change calendar events and contacts through those apps. Mail compose also needs Accessibility, because the message body is pasted into Mail's window through System Events.

Full Disk Access

1. In Terminal, run which node and copy the path it prints.

2. Open System Settings → Privacy & Security → Full Disk Access.

3. Click +.

4. Press Cmd+Shift+G, paste the path, and press Enter.

5. Select node and turn its toggle on.

Automation, Accessibility, and System Events

Run this from Terminal.app, so the prompts attach to node and not to your editor or chat app:

$(which node) $(which apple-tools-mcp) permissions

From a clone, npm run permissions does the same thing. npx apple-tools-mcp permissions also works.

The command prints process.execPath. That path is the node binary macOS will ask about. Click Allow for that binary. If it warns that the command you typed started a different node, run it again with the printed path in front:

/absolute/path/to/node $(which apple-tools-mcp) permissions

Allow node to control Mail, Messages, Contacts, Calendar, and System Events. Each app is its own switch. Allowing Contacts does not allow Mail.

Then open System Settings → Privacy & Security → Accessibility and turn on the same node binary. Without that, Mail compose cannot paste the body.

The command does real work so the prompts can appear. It opens a Mail compose window and throws it away (nothing is sent), lists Messages accounts (nothing is sent), creates and deletes a throwaway contact, lists calendars without creating events, and checks System Events. It exits with an error until Mail, Messages, Contacts, Calendar, and System Events are all allowed.

dry_run on mail_send or messages_send does not talk to those apps, so a dry run will not pop the prompts and will not tell you whether Automation is allowed. A timeout alone does not prove an Automation denial; only an explicit permission error does.

If you clicked Don't Allow, macOS will not ask again. Open System Settings → Privacy & Security → Automation, turn the switch on for that node and that app, then run apple-tools-mcp permissions again.

Do not add node with the + button under Privacy & Security → Contacts or Calendars. Those lists are not how these writes are granted, and on current macOS they often have no Add button.

Leave Mail, Messages, and Contacts running. If they are quit, writes to them often fail even when Automation is allowed. Calendar does not need to stay open.

If your chat app cannot hold the grants

macOS treats these actions as coming from the app that launched the server. A chat app that starts a short-lived MCP process is that app. Some of them cannot be granted Contacts or Calendar access, no matter what you allow for node.

Run the indexer in the next section. It is a normal node process, so the Automation grants you gave node apply. Your MCP client sends writes to it through a local socket at ~/.apple-tools-mcp/writer.sock. When a prompt appears, allow node, not the chat app.

3. Connect your MCP client

Any stdio MCP client can run the server. The command is the same; only the client's settings screen changes.

Global install:

{
  "mcpServers": {
    "apple-tools": {
      "command": "npx",
      "args": ["-y", "apple-tools-mcp"]
    }
  }
}

From a clone, use node and the absolute path to index.js instead of npx.

Claude Desktop keeps this in ~/Library/Application Support/Claude/claude_desktop_config.json. Quit the client completely and reopen it after you save.

The MCP process is short-lived: it exits when the client disconnects. Ongoing indexing belongs on the indexer, not on a wrapper that holds this process open.

When stdin closes, requests already received still get their replies before the process exits (up to two minutes). A script can pipe a whole session in one go:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"script","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mail_search","arguments":{"query":"invoice","limit":5}}}' \
| apple-tools-mcp

4. Indexer

On first use the server builds a search index of your mail, messages, and calendar events. That can take a while if you have a lot of mail. The index is stored in ~/.apple-tools-mcp/vector-index/.

Run the indexer so the index stays current and so writes go through node:

apple-tools-indexer

That command is node index.js --mode=indexer. A global install provides apple-tools-indexer (bin/apple-tools-indexer.js). From a clone, use npm run indexer.

To keep it running across logins, use a LaunchAgent. LaunchAgents do not see your shell PATH, so put in the absolute paths from which node and npm root -g.

Save this as ~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist and replace both paths:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.apple-tools-mcp.indexer</string>
  <key>ProgramArguments</key>
  <array>
    <string>/absolute/path/to/node</string>
    <string>/absolute/path/to/node_modules/apple-tools-mcp/index.js</string>
    <string>--mode=indexer</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/apple-tools-indexer.out.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/apple-tools-indexer.err.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist

The refresh interval is chosen once, when the process starts. The default is 5 minutes. Set INDEX_INTERVAL_MS (30s, 1m, 1h, or a number of milliseconds) or add this to ~/.apple-tools-mcp/config.json:

{
  "indexInterval": "1m"
}

Values are clamped to 15 seconds through 6 hours. A missing config file is fine; the 5-minute default is used.

The indexer keeps its memory bounded for long runs. The vector database's caches are capped at a 64 MB index cache and a 256 MB metadata cache; set APPLE_TOOLS_LANCE_INDEX_CACHE_MB or APPLE_TOOLS_LANCE_METADATA_CACHE_MB (whole megabytes, 1 to 8192) in the LaunchAgent's EnvironmentVariables to change them. Indexed IDs stay in memory between passes, so a pass with no new mail does not re-read the index. Once a day, after a pass that added or removed something, it compacts the index files and removes table versions older than an hour.

If you do not run the indexer, the MCP process indexes when it starts, then exits when the client disconnects. Writes then run inside that process, and macOS attributes them to the app that launched it.

5. Another computer (optional)

The same tools are available over HTTP, with a bearer token on every request. stdio on this Mac does not use the token. The token is a random secret created on first use and kept in your login Keychain (service apple-tools-mcp-http); apple-tools-mcp http-token prints it.

apple-tools-http
apple-tools-mcp http-token

~/.apple-tools-mcp/config.json (the same file as the index interval):

{
  "httpHost": "127.0.0.1",
  "httpPort": 8421
}

127.0.0.1 accepts connections only on this Mac. Set httpHost to a LAN or Tailscale address when a client on another machine should connect. APPLE_TOOLS_HTTP_HOST and APPLE_TOOLS_HTTP_PORT override the file. Do not send the token over an open network.

An example LaunchAgent is examples/com.apple-tools-http.plist. How to point Claude and other clients at it, including apple-tools-http-proxy, is in examples/mcp-client.md.

Index commands

Stop the indexer before a manual rebuild so two processes are not writing the index at once.

# Rebuild (all email history)
npm run build-index

# Optional shorter email lookback
APPLE_TOOLS_INDEX_DAYS_BACK=30 npm run build-index

Your client can also call rebuild_index.

Force a clean rebuild when the index is corrupt or out of date:

launchctl unload ~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist

rm -rf ~/.apple-tools-mcp/vector-index
rm -f ~/.apple-tools-mcp/index-meta.json
rm -f ~/.apple-tools-mcp/indexer.lock

Start the indexer or your MCP client again so it builds a new index.

Watch progress. With the LaunchAgent above:

tail -f /tmp/apple-tools-indexer.err.log

Client logs depend on the app. Claude Desktop:

tail -f ~/Library/Logs/Claude/mcp-server-apple-tools.log

Audit coverage against the source databases:

npm run audit
npm run audit -- --reporter=verbose > audit-report.txt

Your client can also call audit_index.

Available tools

Universal search

Email

Messages

Calendar

Contacts

Index

Write tools

Write tools change your data. They do not use the search index, so they work while the indexer is rebuilding.

Every write tool accepts:

Deletes need confirm: true: mail_trash, calendar_remove, contacts_remove, and contacts_edit when it clears every email or phone. These take one id per call, except mail_trash, which also takes a list (message_ids).

mail_send supports a stable idempotency_key per intended delivery. Accepted delivery is replayed without sending again; changed content with the same key is refused. Without a key, identical accepted content is suppressed without expiry. A new key can name an intentional new delivery only after accepted or proven-unstarted outcomes; changing/removing keys cannot bypass identical pending or terminal not_sent content. Uncertain sends never expire or automatically retry. Missing Sent rows cannot prove a queued send will not finish. Claims persist across processes/restarts in the private ~/.apple-tools-mcp/mail-send-claims directory, containing only hashes and outcome metadata. Dry runs create no claims.

mail_send_reconcile is a separate no-send operation with exact claim/attempt/revision/content identity, protected administrator-issued authority, a persistent cross-process writer fence, and fresh complete Sent and Outbox evidence collected after fencing. It preserves original attempts and appends authoritative audit/state records. not_sent is terminal, not retryable: any later retry requires a separate single-use authorization consumed durably before the existing transport handler. Legacy claims are always ineligible. Installation does not create authority, resolve any historical claim, retry mail, or alter a page ledger. By default, reconciliation refuses without the independently established administrative exclusion/evidence boundary. See the full protocol and transition table.

Send and reconciliation results expose structuredContent.mail_send (schema version 1), separating suppression without current handler entry, attempted-but-unresolved transport, accepted historical replay, terminal suppression, identity/writer/evidence refusal and uncertain bridge handoff. Suppression and uncertainty authorize no retry or page-ledger update. Historical send replay also sets MCP isError so text-only clients cannot mistake it for a newly sent message. Global writer locks/fences do not expire or auto-recover after a crash; availability recovery requires a separate explicit maintenance decision.

A bridge request that expires before execution is rejected. After a handoff with an unknown outcome, local fallback is suppressed. The System Events preflight allows 10 seconds (12-second process cap); timeout reports probe_timeout and unknown permission status, separately from an explicit permission denial.

Sends to more than one person need confirm: true: mail_send and mail_forward when To, Cc, and Bcc add up to more than one address, mail_reply with reply_all: true, and messages_send to several people or to a group chat. A single recipient sends on the first call. mail_draft never sends, so it does not need that confirm.

A dry run or a call that still needs confirm does not deliver anything. The result is ok: false, planned: true, delivered: false, and the client may mark it as an error. The text says DRY RUN or CONFIRMATION REQUIRED. Run it again with dry_run false, and with confirm: true when the tool asked for it.

Responses name the action, ids, and recipients. They do not echo message bodies.

A missing or malformed id or recipient is refused. Calendar times are local datetimes, YYYY-MM-DD HH:MM. Phrases like "next Tuesday" are rejected on writes.

Mail

Pass the RFC822 Message-ID, or the file_path from mail_search or mail_recent and the server reads the Message-ID from the file. mail_archive moves the message to that account's Archive (or All Mail). mail_trash moves it to Trash.

mail_trash with message_ids moves every copy of each message, for example the INBOX copy and the Sent copy of a mail you sent yourself, to that account's Trash. It finds each copy through Mail's database (mail_find uses the same lookup) and checks its Message-ID again before it moves it. One call stops starting new moves after about 35 seconds and reports remaining. Run it again for the rest. Copies that are already in Trash are left alone. Nothing is deleted for good. Mail empties Trash on its own schedule.

body_format: "html" pastes the text into Mail's compose window. Mail may still create its own HTML version. New mail is a new message, not a quoted reply. Reply and forward still include the original.

A send is successful only after the message is in Sent or still in Outbox. If the call times out, check Sent before you try again. Retrying a message that already went out sends a second copy. A timeout is not the same thing as a denied Automation prompt.

Compose needs the Accessibility and System Events grants from the permissions section.

Messages

• to is a phone number in E.164 form (+15551234567) or an Apple ID email.

• chat_id is an existing conversation id, such as iMessage;-;+15551234567 or iMessage;+;chat123456789. It is checked against Messages before anything is sent. That lookup is also how group chats are detected.

• service: auto (default) tries iMessage and can fall back to SMS; imessage and sms pin the service.

• attachment_path is an absolute path to a file that already exists on this Mac. Text and a file can go together.

Calendar

calendar_date and calendar_add report the event id. Pass that id to edit, remove, and RSVP. Run calendar_list_calendars first so a new event lands on the calendar you mean. calendar_add also returns eventkit_id; pass it back on edit and remove.

Recurrence is either structured fields or one raw rule:

alerts_minutes_before takes up to five values, from 0 to 40320 minutes (four weeks). On edit, supplying alerts replaces the existing ones. replace_alerts: true removes them without adding new ones.

calendar_rsvp sets your response on an invitation. If that macOS version will not write it, the tool says so instead of pretending it worked.

Contacts

Use the contact id from contacts_search, contacts_lookup, or contacts_add. Creating a contact needs at least one of first_name, last_name, or organization. Writes go through Contacts, which keeps iCloud in sync.

Examples

{ "name": "mail_send", "arguments": { "to": ["a@example.com"], "subject": "Status", "body": "All good", "dry_run": true } }

{ "name": "mail_send", "arguments": { "to": ["a@example.com"], "subject": "Status", "body": "All good" } }

{ "name": "mail_send", "arguments": { "to": ["a@example.com", "b@example.com"], "subject": "Status", "body": "All good", "confirm": true } }

{ "name": "calendar_add", "arguments": { "calendar_name": "Work", "title": "Standup", "start": "2026-09-21 09:00", "end": "2026-09-21 09:15", "frequency": "weekly", "by_day": ["MO","TU","WE","TH","FR"], "alerts_minutes_before": [10] } }

{ "name": "calendar_remove", "arguments": { "event_id": "EVT-UID", "confirm": true } }

This package does not include Reminders, Notes, FaceTime, or Files.

Example questions

• "Find emails from John about the quarterly report"

• "What messages did I get from Mom last week?"

• "When is my next dentist appointment?"

• "Search for emails about the AWS bill from November"

• "Find all calendar events with Zoom links"

• "What's Sarah's phone number?"

• "Show me all communication with David from last month"

Privacy

Search and the index read your mail, messages, calendar, and contacts on this Mac. Write tools send messages and change events and contacts. Deletes and multi-recipient sends wait for confirm.

Embeddings are computed locally. Nothing is uploaded. The write bridge is a socket in your home directory, not a network port. The server stores no passwords; it uses the Apple apps you are already signed into. The index stays in ~/.apple-tools-mcp/.

Troubleshooting

"Authorization denied" or the databases will not open. Full Disk Access is missing or it was granted to a different node than the one that is running. Repeat the Full Disk Access steps with which node.

A write is denied, or sending mail hangs. Automation was not granted for the node that is actually running. Run apple-tools-mcp permissions from Terminal.app and allow the printed process.execPath for Mail, Messages, Contacts, Calendar, and System Events. Allow node, not the chat app. If you previously clicked Don't Allow, turn the switch on in Automation and run the command again. dry_run does not talk to Mail, so it will not catch this.

"CONFIRMATION REQUIRED". The safety check worked. Pass confirm: true, or use dry_run: true if you only wanted a preview.

Search returns nothing. Check ls ~/.apple-tools-mcp/vector-index/. If it is missing or stale, rebuild with the commands above.

The server does not show up in the client. Confirm the config is valid JSON, then quit the client completely and reopen it.

Development

git clone https://github.com/sfls1397/Apple-Tools-MCP.git
cd Apple-Tools-MCP
npm install
npm test
npm run indexer
npm run build-index
npm run audit
npm run smoke:writes
npm run smoke:writes -- --apply

npm run smoke:writes checks the write path without creating lasting contacts or events. npm run smoke:writes -- --apply performs real creates, edits, and deletes, then removes the test items. The extra -- is required so npm forwards --apply. --apply fails if Mail, Messages, Contacts, or Calendar Automation is missing.

License

MIT License. See LICENSE.

Acknowledgments

• Model Context Protocol SDK

• LanceDB

• Hugging Face Transformers.js

Privacy checks for contributors

Install Gitleaks, then enable the committed hook once in each clone:

git config core.hooksPath .githooks
npm run scan:package

Before a pull request is merged, python3 .security/local-gate.py <PR number> runs Gitleaks, the production npm audit, offline Semgrep, and the unit and security tests on the exact PR head and records the result as the local-gate status.

The hook scans staged changes and fails closed if Gitleaks is unavailable. CI scans all fetched Git history and the exact npm pack --dry-run file list. Release CI repeats the package scan before npm Trusted Publishing. Credential rules are extended with private home paths, relay email, private hostnames and phone shapes. Use neutral example paths and fictional 555 numbers in fixtures. A narrow exception covers the deliberately fake bearer token in authentication unit tests.

Host-specific settings remain in ~/.apple-tools-mcp/config.json; upgrading the global package preserves them. Permission examples derive from the current home and runtime Node binary, so no personal paths belong in the package.