npm package: @foxychat-mcp/apple-imessages
Description: Model Context Protocol (MCP) server for Apple iMessage integration - send messages, read conversations, search contacts
Author: FoxyChat MCP
Latest version: 0.0.2

# 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:
   ```bash
   git clone https://github.com/CodeFox-Repo/Remote-MCP-Servers.git
   cd Remote-MCP-Servers/apple-imessages
   ```

2. Install dependencies:
   ```bash
   bun install
   ```

3. Build the project:
   ```bash
   bun run build
   ```

### From npm (Coming Soon)

```bash
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`):

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

If installed globally via npm:
```json
{
  "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
```bash
bun run build
```

### Testing
```bash
bun test
```

### Code Quality
```bash
bun run check    # Lint and format
bun run lint     # Lint only
bun run format   # Format only
```

### Creating New Tools
```bash
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.