iMessage MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| IMESSAGE_DB | No | Database to read. Point it at a copy to work against a snapshot. | ~/Library/Messages/chat.db |
| GROQ_API_KEY | No | API key for Groq. Required for the default transcription provider. | |
| OPENAI_API_KEY | No | API key for OpenAI. Required when using the 'openai' transcription provider. | |
| ELEVENLABS_API_KEY | No | API key for ElevenLabs. Required for the 'speak' tool and for 'elevenlabs' transcription. | |
| GROQ_WHISPER_MODEL | No | Model used by the 'groq' transcription provider. | whisper-large-v3-turbo |
| IMESSAGE_STATE_DIR | No | Where the cursor is stored. | ~/.imessage-mcp |
| ELEVENLABS_VOICE_ID | No | Voice ID used by the 'speak' tool. | |
| IMESSAGE_TRANSCRIBE | No | Transcription provider: groq, local, openai or elevenlabs. | groq |
| IMESSAGE_WHISPER_MODEL | No | Model used by the 'local' transcription provider. | base |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| inboxA | Messages that have arrived since this tool last ran. The cursor is stored on disk, so anything received while nothing was running is still waiting here rather than lost. Call with peek=true to look without consuming. |
| search_messagesA | Search message history by text, sender, chat, or date range. Reads bodies from both the text column and the encoded attributedBody blob, so it finds messages that plain SQL cannot. |
| list_conversationsB | List chats by most recent activity, with resolved contact names and participants. |
| get_conversationA | Read one conversation in order, oldest first. |
| resolve_contactA | Look up a person in Contacts by name and return their sendable handles. Use before send_message when you know a name but not a number. |
| send_messageA | Send a message to a phone number, email, or chat GUID. Waits for Messages to confirm delivery and reports the failure if it did not go through. |
| send_fileB | Send a file by absolute path. Images and audio render inline in Messages. |
| transcribe_voice_noteA | Transcribe an audio attachment to text. Pass a message rowid to transcribe its attachments, or an absolute path. Uses the configured provider: groq by default, or local to keep the audio on this machine. |
| speakA | Turn text into speech with ElevenLabs and return the audio file path, optionally sending it. Note that Messages shows script-sent audio as an attachment, not as a native voice-note bubble. |
| server_statusB | Database reachability, cursor position, contact count, and which optional tools are installed. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Most tools target clearly distinct purposes: STT (transcribe_voice_note) vs TTS (speak), sending (send_message/send_file), receiving (inbox), and querying (search_messages/list_conversations/get_conversation). The reading tools overlap somewhat—inbox, get_conversation, and search_messages all return messages—but descriptions differentiate them by scope and cursor semantics.
Most tools follow a verb_noun pattern (transcribe_voice_note, search_messages, list_conversations, get_conversation, resolve_contact, send_message, send_file), but several deviate: bare verb 'speak' and bare nouns 'inbox' and 'server_status'. Mixed conventions across the set, though each name is individually readable.
Ten tools is well-scoped for a messaging server that combines send/receive, search, read, contact lookup, voice transcription, TTS, and diagnostics. Each tool earns its place without redundancy.
Core messaging lifecycle is covered: send text/files, receive via inbox, search history, list/read conversations, resolve contacts, plus STT/TTS and status. Minor gaps exist—no message edit/delete, reactions, or group-chat administration—but agents can handle typical workflows.