Skip to main content
Glama
hubermjonathan

imessage-mcp

by hubermjonathan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

imessage-mcp

A minimal MCP server with one tool, text_user, that sends an iMessage to a configured handle. macOS only, Node 18+.

It is only a channel. When an agent should text you, and how often, is for your harness or agent config to decide, not this server.

Setup

npm install && npm run build

Requirements on the machine running the server:

  • IMESSAGE_HANDLE set to the recipient's phone number in E.164 form (+11234567890) or their Apple ID email

  • Messages.app signed in to iMessage

  • Automation permission for Messages (System Settings > Privacy & Security > Automation). macOS prompts once on the first send.

Add to Claude Code

claude mcp add imessage --env IMESSAGE_HANDLE=+11234567890 -- node /absolute/path/to/imessage-mcp/dist/index.js

Tool: text_user

One required field, message (string), sent verbatim. Returns { sent: true }, or an error string explaining why it wasn't sent. It never throws.

Sending is one-way: no receive path, no chat.db reading, no contact lookup, no other tools.

Notes

src/send.applescript is a fixed script file, invoked with the message and handle as arguments, so message content is never interpolated into its source. It omits activate, so sending won't steal focus.