# imessage-send-mcp

A minimal MCP server that sends iMessages via the macOS Messages app using `osascript`. No Full Disk Access required — write-only, never reads your message history.

## What it does

Exposes one tool to Claude Code (or any MCP client):

- **`send_imessage(recipient, message)`** — sends an iMessage or SMS to a phone number or Apple ID email

## Requirements

- macOS (uses `osascript` + Messages app)
- Messages app must be open and signed in to iMessage
- Python 3.11+

## Installation

```bash
pip install imessage-send-mcp
```

Or from source:

```bash
git clone https://github.com/andyjianzhou/imessage-send-mcp
cd imessage-send-mcp
pip install -e ".[dev]"
```

## Add to Claude Code

```bash
claude mcp add-json "imessage-send" '{
  "command": "python3",
  "args": ["-m", "imessage_send_mcp.server"]
}'
```

Then restart Claude Code. The `send_imessage` tool will be available in your next session.

## Usage

Once connected, Claude can send messages like:

```
send_imessage("+14155551234", "Hello from Claude!")
```

Recipients can be:
- Phone number in E.164 format: `+14155551234`
- Apple ID email: `example@icloud.com`

## Security

- **No Full Disk Access needed** — this server only sends messages, never reads `chat.db`
- **No network requests** — runs entirely locally via AppleScript
- **Minimal surface area** — ~50 lines of code, fully auditable

## Development

```bash
pip install -e ".[dev]"
pytest          # run tests
ruff check .    # lint
mypy src        # type check
```

## License

MIT