This server lets you read and search a local iMessage archive and send messages to existing conversations on macOS.
List conversations by recent activity, including chat GUID, participant name, unread count, and last-message preview.
Read messages from one conversation, newest first, with pagination; tapbacks and system events are excluded.
Search message text case-insensitively across the entire archive, optionally restricted to one conversation, with a true match total.
List participants in a conversation with their handles and service.
List unread received messages, newest first.
List attachment metadata only: filename, MIME type, size, direction, and date.
Send a message to an existing conversation by chat GUID.
Cannot start new conversations, and sent messages cannot be recalled.
Allows reading and sending iMessages from the local Messages database on macOS.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iMessage MCP send a text to my wife that I'm on my way"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that reads the local iMessage database and sends messages through Messages.app on macOS.
It runs over stdio for local use and over HTTP for remote use, so a phone or tablet can reach the same server that the laptop uses. That is the point of the project: the desktop-only iMessage integrations work well, but the desktop is the wrong place — the messages worth acting on arrive while you are away from it.
Working, and in use as a remote connector.
Reading is done: the tools below are exercised through a real client over both transports, with password-guarded OAuth 2.1 on the HTTP side and a LaunchAgent behind a tunnel. Sending is done as well, restricted to conversations that already exist.
Starting new conversations, attachment contents, and a full-text search index
are deliberately deferred. See docs/scope.md for the design, the measurements
behind it, and the condition that would bring each deferred item back.
Related MCP server: multimodal-imessage-mcp
Tool | What it does |
| Conversations by recent activity, or by who is in them |
| One conversation, paginated, newest first |
| Case-insensitive across the whole archive, not a window |
| Chat members, resolved names, service |
| Metadata only: filename, MIME type, size, direction |
| What arrived while you were away |
| Existing conversations only, addressed by chat GUID |
Reads are paginated and return both readable text and structured content, with a true total alongside the page — so "3 messages" is never mistaken for the whole answer when 137 matched.
Message text lives in the attributedBody typedstream blob rather than the
text column, which is empty on roughly 99% of messages on a current macOS.
Decoding that blob is the primary path here, not a fallback.
A server that reads a private archive, ingests text from anybody who can message this account, and can send is the whole lethal trifecta in one process. Two rules bound it:
Existing conversations only. There is no way to start a new one, so a hallucinated or mistyped number cannot reach a stranger.
No cross-conversation forwarding. Read tools record which conversation
they showed text from; send_message refuses text that reproduces something
read from a different one, and names where it came from. confirm_forward
overrides that, and is documented as the operator's authorization — never
something message text can grant.
Every result carrying message text is labeled untrusted, in both the text and
the structured half. The honest gap is paraphrase: a sentence written from
memory carries nothing tying it back to its source, and no textual rule finds
it. docs/scope.md states what each defense catches and what it does not.
macOS, with Messages signed in
Python 3.12+ and uv
Full Disk Access for the Python interpreter, to read ~/Library/Messages/chat.db
Contacts needs no second permission: the address book is read as a sqlite file, which Full Disk Access already covers.
Sending needs one more grant — Apple Events control of Messages.app — which macOS prompts for the first time a message is sent. Trigger it deliberately while sitting at the machine rather than letting it ambush a remote client months later.
uv sync
uv run imessage-mcpThat is stdio. For HTTP, set the transport and bind to localhost behind a tunnel or reverse proxy:
IMESSAGE_MCP_TRANSPORT=http \
IMESSAGE_MCP_AUTH=password \
IMESSAGE_MCP_PASSWORD=... \
IMESSAGE_MCP_BASE_URL=https://imessage.example.com \
uv run imessage-mcpAuth applies to the HTTP transport only; stdio takes its security from the fact
that running it means already having a shell on the machine. There is no
version of this server that should be exposed to a network without
IMESSAGE_MCP_AUTH=password — it reads a personal message archive.
Every setting is documented in .env.example: TRANSPORT, HOST, PORT,
STATELESS, AUTH, PASSWORD, BASE_URL, STATE_DIR, DB_PATH, all under
the IMESSAGE_MCP_ prefix.
GET /health is unauthenticated by design so an uptime monitor can poll it. It
reports the resolved interpreter path — a Python patch upgrade silently moves
the binary and voids the Full Disk Access grant, which is the documented way
this service dies — along with the newest message in the database, whether
Messages is running, and the outcome of the last send.
docs/deployment-macos.md covers running it as a LaunchAgent: the plist, the
privacy prompt that hangs the service if the grant is missing, why it must not
be a LaunchDaemon, monitoring, and pushing an update.
scripts/healthcheck.sh and scripts/self-update.sh support that.
uv sync --extra test
uv run pytestThe test suite is offline and runs against a synthetic database built from Apple's schema, including synthesized typedstream blobs, so the real decode path is exercised without committing anybody's messages. It never opens the real database, so it works on a machine that has never sent an iMessage.
This repository is public and hosts a server for a personal archive, so nothing
identifying goes in it — no hostname, no real phone number, no chat GUID.
scripts/scan-secrets.sh checks tracked files for the usual shapes, and CI runs it
alongside the tests. CLAUDE.md has the placeholder conventions.
MIT
List attachment metadata: name, type, size, direction and date.
The files themselves are not read, so this says what was sent, not what is in it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of attachments to return (default: 20) | |
| offset | No | Number of attachments to skip from the start (default: 0) | |
| chat_guid | No | Restrict to one conversation (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and it does disclose a key behavioral trait: the tool does not read file contents, only metadata. It also lists the metadata fields returned. It does not mention ordering, authentication, or rate limits, but the most important behavior is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and output fields, followed by an important caveat. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only metadata-listing tool with three optional parameters and no output schema, the description is adequate: it names the output fields and clarifies the tool does not expose file content. It could be slightly richer by noting ordering or pagination behavior, but those are partly covered by the schema defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even without parameter details in the description. The description adds no parameter-specific semantics; it only describes the output fields, which is relevant but not needed to understand limit, offset, or chat_guid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and names the exact resource ('attachment metadata') plus the fields returned (name, type, size, direction, date). This clearly distinguishes it from sibling tools focused on chats, messages, and participants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this to see attachment metadata, not file contents. The caveat 'files themselves are not read' implies when to choose this tool over content-oriented alternatives, though it does not explicitly name a sibling tool or state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read messages from one conversation, newest first.
Tapbacks and system events such as group renames are excluded: they are stored as messages but are not things anybody said.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of messages to return (default: 50) | |
| offset | No | Number of messages to skip from the start (default: 0) | |
| chat_guid | Yes | The conversation's guid, from list_chats |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds transparency beyond the schema by noting that tapbacks and system events are excluded. With no annotations, this is important behavioral context. It could go further (e.g., pagination behavior, rate limits), but the key exception is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no wasted words. The exclusion note is valuable and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with 3 parameters and full schema coverage. The description covers the main behavior and a key exception. It lacks explicit mention of return format, but that is not required given the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional parameter meaning beyond what is in the schema. The baseline of 3 is appropriate because the schema fully documents parameters, though the description does not enhance their semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads messages from a conversation, newest first. It does not explicitly differentiate from siblings but is unambiguous about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving messages from a specific conversation and excludes tapbacks and system events. It does not explicitly mention alternatives, but the exclusion clarifies scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List who is in a conversation, with their handles and service.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_guid | Yes | The conversation's guid, from list_chats |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool lists participants, but it doesn't disclose any behavioral traits such as whether it's read-only, if it requires specific permissions, or if it returns all participants or only some. For a read-like operation, it's missing details about the return format or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. It states the action and the key output (handles and service) without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is adequate but not complete. It doesn't mention what the output looks like beyond 'handles and service', and it doesn't provide any context about the conversation scope or any edge cases. For a simple tool, it's acceptable, but it could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the only parameter chat_guid is described as 'The conversation's guid, from list_chats'. The description adds the context that it's from list_chats, which is helpful. Since the schema already covers the parameter, the description doesn't need to add much, but it does provide a useful reference to the source of the guid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists participants in a conversation with their handles and service. It specifies the resource (conversation) and the action (list), and the mention of 'handles and service' adds detail. It doesn't explicitly distinguish from siblings, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to know who is in a conversation, but it doesn't explicitly state when to use this vs alternatives. The sibling tools like list_chats and get_messages are related, but no exclusions or alternatives are mentioned. The context is clear but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List received messages that have not been read yet, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of messages to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses that it lists unread messages and orders them newest first, which is basic behavior. It does not disclose potential side effects (likely none for a read operation), or details about pagination, but given the simple nature, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence that conveys the action, resource, and ordering. No unnecessary words. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one parameter and no output schema, the description is adequate. It doesn't explain the return format or fields, but the tool is simple and the schema covers the input. Given the low complexity, this is acceptable, though slightly more detail about the output could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter (limit) with a clear explanation of default value. The description doesn't add extra information about the parameter, but the schema already provides sufficient meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List received messages'), the specific resource ('not been read yet'), and the ordering ('newest first'). It distinguishes from siblings like get_messages (which likely returns all messages) and search_messages (which filters by query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when needing unread messages) and explicitly states the ordering. However, it doesn't explicitly mention alternatives or when not to use it, but the purpose is clear enough to infer the use case from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List conversations, most recently active first.
Each entry carries the chat_guid needed by the other tools, the other participant's name where it is known, how many unread messages it holds, and a preview of the last message.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of conversations to return (default: 20) | |
| offset | No | Number of conversations to skip from the start (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the only source of behavioral context. It does disclose useful behavior such as recency-based ordering and that entries contain metadata rather than full messages, but it does not explicitly state that this is a read-only operation, whether the result is paginated, or any constraints on the returned preview. The verbal 'List' start implies non-mutating behavior, but it is not fully explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the operation and ordering, and the second sentence explains exactly what each result entry contains. There is no filler or unnecessary repetition of the schema names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, the description is nearly sufficient: it names the most important result fields and clarifies that chat_guid links to the other tools. It does not describe the top-level response envelope or pagination behavior, but the schema and list-like nature of the tool keep those gaps minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (limit and offset) already have clear descriptions in the schema. The tool description does not add extra meaning to those parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List conversations') and adds the sorting key ('most recently active first'). It also distinguishes itself from sibling tools by enumerating what each returned entry contains, such as the chat_guid and unread message count, which frames this as the chat-overview tool rather than a message-level or search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the main usage context clear: list chats to get chat_guid and summary data that other tools need. It does not explicitly state exclusions or when to prefer a sibling tool instead, but the connection to chat_guid, participants, unread counts, and last-message preview provides a strong sense of when this should be the first tool invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search message text across conversations, case-insensitively.
The entire history is searched, not a recent window, so a total of 0 means the text is genuinely not there. The total is a true count of matches; limit bounds only how many are returned.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of matches to return (default: 20) | |
| query | Yes | Text to look for | |
| offset | No | Number of matches to skip from the start (default: 0) | |
| chat_guid | No | Restrict the search to one conversation (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that search is case-insensitive, covers full history, and that 'total' is an exact count while 'limit' only affects returned results. This is valuable context that helps the agent interpret results correctly. No contradiction with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. It front-loads the core purpose and immediately adds critical behavioral details about search scope and result semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a read-only search operation, and the description covers the key behavioral aspects: case sensitivity, scope, and result counting. With no output schema, it could mention the structure of returns, but the description is adequate for a search tool with these parameters. Minor gap is lack of detail on return format or sorting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are documented in the schema. The description adds some value by clarifying the behavior of 'limit' and 'total', but it doesn't explain the meaning of 'offset' or 'chat_guid' beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool searches message text across conversations with case-insensitivity. It distinguishes from siblings like list_chats and get_messages by emphasizing full-text search across all conversations, though it doesn't directly name a sibling as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: searching is case-insensitive and covers the entire history, meaning a zero result is definitive. However, it doesn't explicitly state when to use this tool versus alternatives like get_messages or list_chats, which are for reading specific messages or listing conversations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to an existing conversation.
Only conversations that already exist can be addressed, by the chat_guid from list_chats. There is no way to start a new conversation, so this cannot reach somebody who has not been talked to before.
A sent message cannot be recalled.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The message to send | |
| chat_guid | Yes | The conversation's guid, from list_chats |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals two critical constraints: messages cannot be recalled and new conversations cannot be initiated. This adds meaningful context beyond the schema, though it does not mention error states, authentication, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states the core action, the second explains the existential constraint, and the third notes irreversibility. No filler or redundant phrasing; the structure is front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the essential operational context: what it does, the prerequisite for existing conversations, and the irreversible nature of sending. It omits potential error handling or side effects, but these are not critical given the tool's simplicity and the complete parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already offers 100% parameter coverage with concise descriptions for both text and chat_guid. The description adds value by reinforcing that chat_guid must come from list_chats and be an existing conversation, giving the agent a clearer semantic understanding of the parameter's provenance and validity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Send a message to an existing conversation,' clearly identifying the verb (send), resource (message), and scope (existing conversation). This distinguishes it from sibling read-only tools like get_messages and search_messages, which focus on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states that only existing conversations can be addressed and that there is no way to start a new conversation, providing clear when-to-use and when-not-to-use guidance. It also references list_chats as the source for chat_guid, implying the correct workflow, though it does not explicitly contrast with alternative send-related tools (none exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_attachmentsget_messagesget_participantsget_unreadlist_chatssearch_messagessend_messageScored across 7 tools
Each tool targets a distinct aspect of iMessage: listing chats, reading messages, searching, participants, unread, attachments, and sending. There is no overlap in purpose, and the descriptions clarify boundaries (e.g., get_messages excludes tapbacks, get_attachments only lists metadata).
All tool names follow a consistent verb_noun pattern: list_chats, get_messages, search_messages, get_participants, get_unread, get_attachments, send_message. The verbs are uniform (list/get/search/send) and nouns are clear, making the set predictable.
Seven tools is well-scoped for an iMessage server: it covers the core read and send operations without redundancy. Each tool earns its place, and the count is within the ideal 3-15 range.
The surface covers the main iMessage workflows: listing chats, reading/searching messages, checking unread, viewing participants and attachments, and sending. The only notable gap is the inability to start a new conversation, which is explicitly documented and may be a platform limitation, but it is a real dead end for reaching new contacts.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
