apple-tools-mcp

An MCP (Model Context Protocol) server that provides semantic search across Apple Mail, Messages, and Calendar on macOS. Use natural language to search your emails, iMessages, and calendar events 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. Open System Settings → Privacy & Security → Full Disk Access
2. Click the + button
3. Navigate to your Node.js binary:
   • For Homebrew: /opt/homebrew/bin/node
   • For nvm: ~/.nvm/versions/node/v[VERSION]/bin/node
   • To find yours: which node
4. Enable the toggle for Node.js

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:

| Tool | Description | |------|-------------| | search_emails | Search emails by content, sender, subject | | search_messages | Search iMessages and SMS | | search_calendar | Search calendar events | | search_all | Search across all sources | | get_email | Get full email by ID | | get_message | Get full message thread | | get_calendar_event | Get event details |

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"

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

Development

# Clone the repo
git clone https://github.com/sfls1397/apple-tools-mcp.git
cd apple-tools-mcp

# Install dependencies
npm install

# Run tests
npm test

# 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