Skip to content
Sign inBook setup callStart free trial

Docs

MCP server

The autoMessage MCP server exposes your iMessage account as tools any Model Context Protocol client can call. Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Codex, Cline, n8n, and every other MCP-compatible client.

Before you start

  • Grab your API key from Settings in the dashboard. Keep it secret — anyone with the key can read and send your iMessages.
  • The Mac app must be installed and running for outbound sends to actually deliver. The MCP server reads and writes through our REST API; the Mac connector does the iMessage work.
  • The package is published to npm as @stockmandigital/automessage-mcp. No global install needed — npx pulls the latest version on first run.

Claude — hosted MCP (no install)

The simplest way to connect — nothing to install. Claude talks to our hosted MCP server directly over HTTPS. In Claude on web or desktop, open Settings → Connectors → Add custom connector, then enter:

Name
autoMessage
Remote MCP server URL
https://automessage-mcp-tfsfyvwypq-uc.a.run.app/mcp?key=<your-key>

Leave the OAuth fields blank and click Add — autoMessage's tools appear in Claude's tool picker. Swap <your-key> for your API key from Settings.

One caveat: this method carries your key in the URL, so it can show up in server logs. It's perfect for getting started; on shared machines prefer a header-based install below. Your key is rotatable from Settings anytime.

Claude Code

One command. Restart Claude Code afterward.

claude mcp add automessage --scope user -- \
  env AUTOMESSAGE_API_KEY=<your-key> \
  npx -y @stockmandigital/automessage-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "automessage": {
      "command": "npx",
      "args": ["-y", "@stockmandigital/automessage-mcp"],
      "env": { "AUTOMESSAGE_API_KEY": "<your-key>" }
    }
  }
}

Fully restart Claude Desktop (Cmd-Q, not just close the window) so it re-reads the config.

Cursor, Codex, Cline, ChatGPT Desktop, n8n

Same shape as Claude Desktop above — any MCP-compatible client accepts the same command / args / env config. Consult each client's docs for exactly where its MCP config file lives.

Tools exposed

Every REST endpoint has a matching MCP tool. Clients see them as callable functions in their normal tool picker.

list_conversations
List your iMessage threads, newest first.
get_conversation
Fetch a single thread by id.
list_messages
Paginated messages in a thread, with sender names resolved.
get_message
Look up any single message by its iMessage GUID.
send_message
Queue an outbound iMessage for delivery through your Mac connector.
list_drafts
See queued and recently-sent drafts.
get_draft
Poll a specific draft to check delivery status.
update_draft
Edit the body of a draft that has not sent yet.
cancel_draft
Soft-cancel an unsent draft.
list_contacts
Read your address book.
upsert_contact
Create or update a contact (idempotent per handle).
delete_contact
Remove an API-managed contact.
status
API health, your account info, and whether your Mac connector is online.

Try it

Sample prompts once the server is connected:

  • "Show me my last 5 iMessage threads and summarize the unread ones."
  • "Draft a reply to Jane confirming 2pm and queue it — don't send yet."
  • "Poll draft aB3dE5… until it sends, then tell me the sentMessage path."
  • "Add Jane Appleseed to my contacts with phone +14155551234."

Deliverability

Sends happen through your own Mac and your own Apple ID. We surface deliverability guidance instead of hard caps — you stay in control. Apple's observed soft ceiling is ~50 new conversations per Apple ID per day; sustained bursts above ~200 messages/hour tend to draw throttling. Watch the dashboard's deliverability panel for early warnings.

Related