iMessage + Claude Code Setup

Get Claude auto-responding to your iMessages on a fresh Mac in 6 steps.

Prerequisites

A Mac with Messages.app signed into your Apple ID
Claude Code installed (npm install -g @anthropic-ai/claude-code or desktop app)

Setup Steps

1 Install Bun

The iMessage MCP server runs on Bun. Install it:

curl -fsSL https://bun.sh/install | bash

After install, Bun lives at ~/.bun/bin/bun. Your ~/.zshrc gets updated automatically, but MCP servers don't inherit your shell PATH. Fix this by symlinking into a system-wide location:

sudo mkdir -p /usr/local/bin
sudo ln -s ~/.bun/bin/bun /usr/local/bin/bun

This symlink is critical. Without it, the MCP server fails to start because it can't find bun.

Verify:

bun --version

2 Grant Full Disk Access

Claude reads ~/Library/Messages/chat.db directly. Without Full Disk Access, the server crashes on startup.

Open System Settings → Privacy & Security → Full Disk Access
Add your terminal app (Terminal, iTerm2, Warp, etc.)
If running Claude Code from an IDE, add that IDE too

Verify:

ls ~/Library/Messages/chat.db

If you see the file path printed, FDA is working.

If you get "Operation not permitted", FDA is not granted.

3 Enable the iMessage Plugin

In Claude Code, run:

/install-plugin imessage

Or manually add to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "imessage@claude-plugins-official": true
  }
}

Restart Claude Code after enabling the plugin.

4 Configure Access (Allowlist)

By default, the channel uses an allowlist policy. Self-chat (texting yourself) always works. To allow other phone numbers, run in Claude Code:

/imessage:access allow +15551234567

Replace with the actual phone number in E.164 format. The config lives at ~/.claude/channels/imessage/access.json:

{
  "dmPolicy": "allowlist",
  "allowFrom": ["+15551234567"],
  "groups": {},
  "pending": {}
}

5 Set Up Auto-Responses

The MCP server reads and sends messages, but Claude won't auto-respond unless told to. In a Claude Code session, run:

/loop 1m check for new iMessage messages using chat_messages and reply to any unresponded messages in a helpful, friendly way

This polls every minute and replies to new messages automatically.

The loop only runs while the Claude Code session is active. If you close the terminal, auto-responses stop.

Loops auto-expire after 7 days. Re-run the command to restart.

6 Test It

Send a text to your Mac's phone number or iMessage address from another device
Wait up to 1 minute for the loop to pick it up
You should see Claude reply in the iMessage thread

To verify the first send, macOS will prompt for Automation permission for Messages.app — click Allow.

Troubleshooting

"MCP server failed to start"

bun is not on the system PATH — create the symlink from Step 1
Run which bun — if nothing, the symlink is missing
Make sure /usr/local/bin exists: sudo mkdir -p /usr/local/bin

"Operation not permitted" / can't read chat.db

Full Disk Access not granted — see Step 2
Grant FDA to the correct app (the terminal or IDE running Claude Code)

Messages send but no auto-reply

Make sure the /loop command is running in an active Claude Code session
Check the sender's number is in the allowlist (/imessage:access)

First send triggers macOS Automation prompt

Click Allow when macOS asks for Automation permission for Messages.app — one-time only

Quick Reference

Plugin config	`~/.claude/settings.json`
Access config	`~/.claude/channels/imessage/access.json`
MCP server	`~/.claude/plugins/.../imessage/.mcp.json`
iMessage DB	`~/Library/Messages/chat.db`
Bun binary	`~/.bun/bin/bun` → `/usr/local/bin/bun`