Skip to main content
Glama
deenesjakoruzh
wyattjoh

iMessage MCP

by wyattjoh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

iMessage MCP

一个包含用于在 macOS 上访问 iMessage 的包的 Deno 单体仓库：

功能特性

  • 按文本内容、联系人或日期范围搜索消息

  • 获取最近的消息

  • 列出所有聊天/对话

  • 获取所有联系人/句柄

  • 从特定聊天中检索消息

  • 按姓名搜索 macOS 通讯录，并关联 iMessage 句柄 ID

Related MCP server: imessage-mcp

系统要求

  • macOS（iMessage 仅在 macOS 上可用）

  • Deno 2.x 或更高版本

  • 对 ~/Library/Messages/chat.db 的读取权限，或对通过 IMESSAGE_DB_PATH 配置的自定义数据库的读取权限

  • 对 ~/Library/Application Support/AddressBook/ 的读取权限（用于联系人搜索）

包

@wyattjoh/imessage

用于访问 iMessage 数据的核心库：

deno add @wyattjoh/imessage
import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";

const db = await openMessagesDatabase();
const results = await searchMessages(db, { query: "hello" });
db.close();

查看完整文档

@wyattjoh/imessage-mcp

用于 LLM 集成的 MCP 服务器：

# Run directly from JSR
deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp

# Or install globally
deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp

如需与 Claude Desktop 应用集成，请将其添加到您的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}

自定义消息数据库

设置 IMESSAGE_DB_PATH 以打开其他位置的只读 SQLite 数据库，例如定期刷新的 chat.db 快照：

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env=IMESSAGE_DB_PATH",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ],
      "env": {
        "IMESSAGE_DB_PATH": "/tmp/imessage-snapshot.sqlite"
      }
    }
  }
}

该进程需要对自定义文件具有读取权限。如果 Deno 没有读取 IMESSAGE_DB_PATH 的权限，或者该变量为空或未设置，库将使用 ~/Library/Messages/chat.db，而不会提示环境访问权限。

选项 2：从源码构建

  1. 克隆此仓库

  2. 安装依赖：

    deno cache src/index.ts

  3. 运行服务器：

    deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts
# Or use the task:
deno task start

可用工具

  1. search_messages - 使用筛选条件搜索消息

    • query（可选）：要搜索的文本

    • handle（可选）：用于筛选的电话号码或电子邮件

    • startDate（可选）：开始日期的 ISO 日期时间字符串

    • endDate（可选）：结束日期的 ISO 日期时间字符串

    • limit（可选）：最大结果数（1-200，默认：100）

    • offset（可选）：分页偏移量（默认：0）

  2. get_recent_messages - 获取最近的消息

    • limit（可选）：消息数量（1-100，默认：20）

    • offset（可选）：分页偏移量（默认：0）

  3. get_chats - 列出所有对话

    • limit（可选）：聊天数量（1-200，默认：50）

    • offset（可选）：分页偏移量（默认：0）

  4. get_handles - 获取所有联系人/句柄

    • limit（可选）：句柄数量（1-200，默认：100）

    • offset（可选）：分页偏移量（默认：0）

  5. get_messages_from_chat - 从特定聊天中获取消息

    • chatGuid（必填）：聊天 GUID

    • limit（可选）：消息数量（1-200，默认：50）

    • offset（可选）：分页偏移量（默认：0）

  6. search_contacts - 按姓名搜索 macOS 通讯录并获取电话号码

    • firstName（必填）：要搜索的名字（例如 'John'）

    • lastName（可选）：要搜索的姓氏（例如 'Smith'）。如果省略，则搜索所有姓名字段

    • limit（可选）：最大结果数（1-200，默认：50）

    • offset（可选）：分页偏移量（默认：0）

    • 返回包含电话号码和电子邮件地址的联系人信息，可用作句柄参数

    • 直接在 macOS AddressBook 数据库中搜索，以获得更好的性能和可靠性

分页示例

所有工具现在都支持使用 limit 和 offset 参数进行分页，并返回分页元数据：

// Get first 20 recent messages
get_recent_messages({ limit: 20, offset: 0 });

// Get next 20 recent messages (page 2)
get_recent_messages({ limit: 20, offset: 20 });

// Get first 10 chats
get_chats({ limit: 10, offset: 0 });

// Get messages 51-100 from a specific chat
get_messages_from_chat({
  chatGuid: "iMessage;-;+15551234",
  limit: 50,
  offset: 50,
});

// Search with pagination
search_messages({
  query: "meeting",
  limit: 100,
  offset: 200,
});

// Search contacts with pagination
search_contacts({
  firstName: "John",
  lastName: "Smith",
  limit: 50,
  offset: 0,
});

带分页元数据的响应格式

所有分页工具现在都以此格式返回响应：

{
  "data": [
    // Array of results (messages, chats, handles, etc.)
  ],
  "pagination": {
    "total": 1250, // Total number of results available
    "limit": 100, // Current page size
    "offset": 200, // Current offset
    "hasMore": true, // Whether there are more results to fetch
    "page": 3, // Current page number (1-indexed)
    "totalPages": 13 // Total number of pages
  }
}

此元数据可帮助您：

  • 无需获取所有结果即可了解结果总数

  • 确定是否还有更多页面可获取（hasMore）

  • 计算您当前所在的页面以及总页数

  • 构建正确的分页 UI 组件

安全说明

  • 此服务器以只读权限访问 iMessage 数据库

  • 无法发送或修改任何消息

  • 服务器仅访问本地数据

开发

这是一个 Deno 工作区单体仓库。从根目录运行的所有命令都会影响所有包。

# Clone the repository
git clone https://github.com/wyattjoh/imessage-mcp.git
cd imessage-mcp

# Cache dependencies
deno cache packages/*/mod.ts

# Format all code
deno task fmt

# Lint all packages
deno task lint

# Type check all packages
deno task check

# Run tests
deno task test

# Run MCP server locally
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

# Publish packages (CI/CD)
deno publish

处理单个包

# Work on @wyattjoh/imessage
cd packages/imessage
deno test --allow-read --allow-env --allow-ffi --allow-sys=homedir

# Work on @wyattjoh/imessage-mcp
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • iMessage MCP

    4ndylg
    A
    license
    Not graded
    quality
    D
    maintenance
    Read-only MCP server for local macOS Messages database, enabling querying of chats, messages, attachments, and metadata.
    246 npm
    MIT

  • imessage-mcp-server

    tinyxia
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for reading and sending iMessages on macOS. Exposes iMessage history and send capabilities through tools like list_conversations and send_imessage.
    6 npm
    MIT