Apple-Tools-MCP by sfls1397 - MCP Server

apple-tools-mcp

An MCP (Model Context Protocol) server that provides semantic search across Apple Mail, Messages, Calendar, and Contacts on macOS. Use natural language to search your emails, iMessages, calendar events, and contacts directly from Claude.

Features

Semantic Search: Find emails, messages, and events using natural language queries
Vector Indexing: Uses LanceDB for fast similarity search with local embeddings
Privacy-First: All processing happens locally on your Mac - no data leaves your machine
Smart Deduplication: Handles IMAP duplicates, prioritizing INBOX over Junk/Trash
Date Intelligence: Understands queries like "last week", "yesterday", "March 2024"

Requirements

macOS (Ventura 13.0 or later recommended)
Node.js 18.0 or later
Claude Desktop app
Full Disk Access permission for the Node.js binary

Installation

1. Install the package

npm install -g apple-tools-mcp

2. Grant Full Disk Access

The MCP server needs access to read your Mail, Messages, and Calendar databases.

First, find your Node.js path by running in Terminal:
```
which node
```
This will output something like /opt/homebrew/bin/node or /usr/local/bin/node
Open System Settings → Privacy & Security → Full Disk Access
Click the + button
Press Cmd+Shift+G to open the "Go to Folder" dialog
Paste the path from step 1 (e.g., /opt/homebrew/bin/node) and press Enter
Select the node file and click Open
Ensure the toggle for Node.js is enabled

3. Configure Claude Desktop

Add to your Claude Desktop config file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

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

4. Restart Claude Desktop

Quit and reopen Claude Desktop to load the MCP server.

Building the Index

On first use, the server will automatically build a vector index of your recent emails, messages, and calendar events. This may take a few minutes depending on the volume of data.

You can manually rebuild the index:

# Index last 30 days (default)
npx apple-tools-mcp build-index

# Index more history
APPLE_TOOLS_INDEX_DAYS_BACK=90 npx apple-tools-mcp build-index

The index is stored in ~/.apple-tools-mcp/vector-index/.

Available Tools

Once configured, Claude can use these tools:

Universal Search

Tool	Description
`smart_search`	Intelligent search across all sources - automatically determines which to search
`person_search`	Find ALL communication with a person across Mail, Messages, and Calendar

Email Tools

Tool	Description
`mail_search`	Semantic search for emails with filters (sender, recipient, attachments, mailbox)
`mail_recent`	Get most recent emails (supports unread filter)
`mail_date`	Get emails from a specific date ("today", "yesterday", "Nov 13")
`mail_read`	Read full email content by file path
`mail_senders`	List most frequent email senders
`mail_thread`	Get all emails in a conversation thread

Messages Tools

Tool	Description
`messages_search`	Semantic search for iMessages/SMS with filters
`messages_recent`	Get most recent messages
`messages_conversation`	Get full conversation history with a contact
`messages_contacts`	List all contacts you've messaged

Calendar Tools

Tool	Description
`calendar_search`	Semantic search for events with filters
`calendar_date`	Get events on a specific date
`calendar_upcoming`	Get next N upcoming events
`calendar_week`	Get all events for current or future week
`calendar_free_time`	Find available time slots on a date
`calendar_recurring`	List recurring events

Contacts Tools

Tool	Description
`contacts_search`	Search contacts by name, email, phone, or organization
`contacts_lookup`	Look up a specific contact's full details

Admin Tools

Tool	Description
`rebuild_index`	Rebuild search index for one or all sources
`audit_index`	Audit index health and coverage

Example Queries

Ask Claude things like:

"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 & Security

Local Processing: All embeddings are generated locally using Xenova/Transformers
No Cloud Services: No data is sent to external servers
Read-Only: The server only reads data, never modifies your Mail/Messages/Calendar
Your Data: The vector index is stored locally in your home directory

Troubleshooting

"Authorization denied" errors

Ensure Node.js has Full Disk Access (see Installation step 2).

Empty search results

Check that the index was built: ls ~/.apple-tools-mcp/vector-index/
Rebuild the index if needed: npx apple-tools-mcp build-index

Server not appearing in Claude

Verify your config file syntax is valid JSON
Restart Claude Desktop completely (Cmd+Q, then reopen)
Check Claude's MCP logs for errors

Force rebuild the index

If the index becomes corrupted or out of sync:

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

# Restart Claude Desktop to trigger a fresh rebuild

Monitor indexing progress

Watch the MCP server logs in real-time:

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

Audit the index

Check index health and coverage:

# Quick audit
npm run audit

# Detailed audit saved to file
npm run audit -- --reporter=verbose > audit-report.txt

Development

# Clone the repo
git clone https://github.com/sfls1397/Apple-Tools-MCP.git
cd Apple-Tools-MCP

# Install dependencies
npm install

# Install test dependencies
npm install -D vitest @vitest/coverage-v8 fast-check

# Run tests
npm test

# Run tests with verbose coverage report
npx vitest run --coverage --reporter=verbose

# Build index with debug output
npm run build-index

# Run audit to check index health
npm run audit

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Run the tests: npm test
Submit a pull request

License

MIT License - see for details.

Acknowledgments

Built with the Model Context Protocol SDK
Vector search powered by LanceDB
Local embeddings via Xenova/Transformers