Apple iMessages MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Apple's iMessage and Contacts applications on macOS. Send messages, read conversations, search contacts, and manage communications directly through Claude.

🚀 Features

• Send iMessages: Send text messages to contacts via phone number or email
• Read Conversations: Read message history from specific contacts
• Unread Messages: Get all unread messages across conversations
• Contact Search: Search and retrieve contact information
• Full Disk Access: Securely access Messages database with proper permissions

📋 Requirements

• macOS: This server only works on macOS systems
• Messages App: Apple Messages must be configured and running
• Full Disk Access: Required for reading message database
• Node.js: Version 18 or higher
• Bun: For development and building

🔧 Installation

From Source

1. Clone the repository:

   git clone https://github.com/CodeFox-Repo/Remote-MCP-Servers.git
   cd Remote-MCP-Servers/apple-imessages

2. Install dependencies:

   bun install

3. Build the project:

   bun run build

From npm (Coming Soon)

npm install -g @foxychat-mcp/apple-imessages

⚙️ Configuration

1. Grant Full Disk Access

For the server to read iMessages, you need to grant Full Disk Access:

1. Open System Settings (or System Preferences on older macOS)
2. Go to Privacy & Security → Privacy
3. Select "Full Disk Access" from the left sidebar
4. Click the lock icon and authenticate
5. Find and enable Claude in the list (or add it with the + button)
6. Restart Claude for changes to take effect

2. Claude Desktop Configuration

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-imessages": {
      "command": "node",
      "args": ["/path/to/your/apple-imessages/dist/main.js"]
    }
  }
}

If installed globally via npm:

{
  "mcpServers": {
    "apple-imessages": {
      "command": "npx",
      "args": ["-y", "@foxychat-mcp/apple-imessages"]
    }
  }
}

🛠️ Available Tools

send_imessage

Send an iMessage to a contact.

• recipient: Phone number or email address
• message: Text content to send

search_contacts

Search contacts by name, phone, or email.

• query: Search term

read_imessages

Read message history from a specific contact.

• phone_number: Contact's phone number
• limit: Number of messages to retrieve (default: 10)

get_unread_imessages

Get all unread messages.

• limit: Number of messages to retrieve (default: 10)

📚 Resources

contacts://all

Access to all contacts from the Contacts app in JSON format.

🔒 Privacy & Security

This server:

• Only accesses data when explicitly requested through MCP tools
• Requires explicit Full Disk Access permission
• Does not store or transmit personal data
• Operates entirely locally on your machine
• Uses Apple's official APIs and databases

🛠️ Development

Building

bun run build

Testing

bun test

Code Quality

bun run check    # Lint and format
bun run lint     # Lint only
bun run format   # Format only

Creating New Tools

bun run create-tool <tool-name>

📂 Project Structure

apple-imessages/
├── src/
│   ├── tools/              # MCP tools implementation
│   │   ├── sendImessage/
│   │   ├── searchContacts/
│   │   ├── readImessages/
│   │   └── getUnreadImessages/
│   ├── utils/              # Shared utilities
│   │   ├── appleScript.ts  # AppleScript execution
│   │   ├── database.ts     # Message database access
│   │   ├── messageReader.ts # Message parsing
│   │   └── retry.ts        # Retry mechanisms
│   ├── main.ts             # Server entry point
│   └── types.ts            # Type definitions
└── dist/                   # Built files

🐛 Troubleshooting

"Cannot access Messages database"

• Ensure Full Disk Access is granted to Claude
• Restart Claude after granting permissions
• Check that Messages app is properly configured

"AppleScript error"

• Ensure Messages app is running
• Check that the recipient exists in your contacts
• Verify iMessage is properly set up

Permission Issues

• Make sure you're running on macOS
• Verify the built file has execute permissions: chmod +x dist/main.js

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.