iMessage MCP

by duanefields

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation5/5
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).
Naming Consistency5/5
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.
Tool Count5/5
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.
Completeness4/5
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.
Average 4/5 across 7 of 7 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![imessage-mcp MCP server](https://glama.ai/mcp/servers/duanefields/imessage-mcp/badges/card.svg)](https://glama.ai/mcp/servers/duanefields/imessage-mcp)

Score Badge

Copy to your README.md:

[![imessage-mcp MCP server](https://glama.ai/mcp/servers/duanefields/imessage-mcp/badges/score.svg)](https://glama.ai/mcp/servers/duanefields/imessage-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/duanefields/imessage-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server