Mac Messages Host

Mac の Apple Messages（iMessage/SMS）履歴全体を、AI エージェント向けに読み取り専用で提供します — REST/OpenAPI とストリーミング対応 HTTP MCP 上で提供される単一のバッチツールです。

• 単一ツール、バッチリクエスト: 単一の messages(requests: str) ツールが、JSON リクエストの配列を受け取り、対応する JSON レスポンスの配列を返します。1 回の呼び出しで多数の独立した操作を実行できます。REST（POST /api/messages）と MCP（/mcp/）の両方で同一に提供されます。

• 設計上読み取り専用: データベースは SQLite の mode=ro で開かれ、書き込み経路はありません。送信、編集、削除は一切できません。

• 最新の macOS 本文デコード: attributedBody の typedstream ブロブ（Ventura+）に保存されたメッセージ本文と、message_summary_info plist 内の編集履歴を透過的にデコードします。

• 自動生成のツールプロンプト: AI 向けプロンプトは Pydantic モデルから生成され（約 615 gpt-4o トークン、tiktoken でカウントされ、テストで保証されています）。tool_prompt.md のスナップショットはドリフトテストで同期が維持されています。

Install

macOS 上で Python 3.11+ が必要です。

pip install .            # or: pip install -e . for development
mmhost info              # permission check + database status
mmhost start             # serve API + MCP on http://127.0.0.1:8761

macOS のアクセス権限（重要）

~/Library/Messages/chat.db は macOS TCC によって保護されています。mmhost を実行するプロセスには フルディスクアクセスが必要です。

システム設定 → プライバシーとセキュリティ → フルディスクアクセス → ターミナルアプリ（またはサーバーを起動するもの）を有効にし、再起動してください。

mmhost info を実行すると、データベースが読み取り可能かどうかがすぐにわかります。

Related MCP server: imessage-mcp

Endpoints

Auth

admin_token（永続設定、MMHOST_ADMIN_TOKEN、または --admin-token）が設定されている場合は、Authorization: Bearer <token> が必要です。トークンが設定されていない場合は、アクセスがオープンになります。デフォルトでサーバーが 127.0.0.1 にバインドされるため安全です。

Request kinds

• get_info — データベースのステータス、件数、履歴の日付範囲

• list_chats — 最近のアクティビティ順の会話一覧（フィルタ、ページネーション）

• get_chat — チャットのトランスクリプト（before で過去の履歴をページング）

• get_recent — すべてのチャットにわたる最新メッセージ（since でポーリング）

• search_messages — メッセージ本文に対する大文字小文字を区別しない部分文字列検索

正確な AI 向けドキュメント（モデルから生成）については tool_prompt.md を参照してください。

Example

curl -s http://127.0.0.1:8761/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"requests": "[{\"kind\":\"list_chats\",\"limit\":3}]"}'

MCP クライアント設定

{
  "mcpServers": {
    "mac-messages": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8761/mcp/"
    }
  }
}

Configuration

プラットフォームの設定ディレクトリ（macOS では ~/Library/Application Support/mac_messages_host/config.json）に永続化されます。場所は MMHOST_CONFIG で上書きできます。サーバーレベルの設定のみです — example.env を参照してください。

Development

pip install -e '.[dev]'
pytest
# after changing request models:
python -m tests.regenerate_tool_prompt

アーキテクチャは oWoHo AI Tool Server パターン（純粋なコアライブラリ + そこから派生した FastAPI/FastMCP/CLI インターフェース）に従っており、reddit_tool_server や obsidian_ai_miniserver と同様です。

License

MIT — LICENSE.md を参照してください。