apple-tools-mcp

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.

1. 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

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

3. Click the + button

4. Press Cmd+Shift+G to open the "Go to Folder" dialog

5. Paste the path from step 1 (e.g., /opt/homebrew/bin/node) and press Enter

6. Select the node file and click Open

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

Email Tools

Messages Tools

Calendar Tools

Contacts Tools

Admin Tools

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

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

Server not appearing in Claude

1. Verify your config file syntax is valid JSON
2. Restart Claude Desktop completely (Cmd+Q, then reopen)
3. 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:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the tests: npm test
5. Submit a pull request

License

MIT License - see LICENSE for details.

Acknowledgments

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