MCP Iphone Callhistory

mcp iphone通话记录

模型上下文协议（MCP）服务器，为AI助手提供对macOS iPhone通话历史的访问。

特性

• 最近通话：获取过去N小时的通话记录
• 联系人搜索：按联系人姓名或电话号码搜索呼叫
• 通话统计：分析呼叫模式（呼入/呼出、接听/未接、持续时间）
• 联系人列表：从通话记录中获取最频繁的联系人

运作原理

此MCP服务器查询 CallHistory.storedata macOS从iPhone同步的SQLite数据库。数据库位于：

~/Library/Application Support/CallHistoryDB/CallHistory.storedata

所有查询均为 只读的 不要修改您的通话记录。

安装

cd /Users/dshanklinbv/repos/mcp-iphone-callhistory
npm install
npm run build

配置

添加到您的Claude Code MCP设置中(~/.config/claude-code/mcp_settings.json):

{
  "mcpServers": {
    "callhistory": {
      "command": "node",
      "args": [
        "/Users/dshanklinbv/repos/mcp-iphone-callhistory/dist/index.js"
      ]
    }
  }
}

可用工具

get_recent_calls

获取指定小时内的最近通话记录。

参数：

• hours （数字，可选）：回顾的小时数（默认值：24）
• contact （字符串，可选）：按联系人姓名或电话号码筛选

例子：

// Get all calls from last 24 hours
get_recent_calls({ hours: 24 })

// Get Emily's calls from last week
get_recent_calls({ hours: 168, contact: "Emily" })

退货：

[
  {
    "id": 12345,
    "date": "2025-12-07T15:30:00.000Z",
    "duration": 180,
    "address": "+15551234567",
    "name": "Emily Rothrock",
    "answered": true,
    "outgoing": false,
    "read": true,
    "callType": 1,
    "uniqueId": "ABC123"
  }
]

search_calls_by_contact

搜索特定联系人的通话记录。

参数：

• contact （字符串，必填）：联系人姓名或电话号码

例子：

search_calls_by_contact({ contact: "Emily" })

退货： 最多100条最新通话记录的数组（格式与 get_recent_calls)

get_call_stats

获取通话统计数据以供分析。

参数：

• contact （字符串，可选）：按特定联系人筛选
• days （数字，可选）：要分析的天数（默认值：30）

例子：

// Overall stats for last 30 days
get_call_stats({ days: 30 })

// Emily's call stats
get_call_stats({ contact: "Emily", days: 30 })

退货：

{
  "totalCalls": 150,
  "incomingCalls": 75,
  "outgoingCalls": 75,
  "answeredCalls": 120,
  "missedCalls": 30,
  "totalDuration": 18000,
  "averageDuration": 120
}

get_contacts

获取按通话频率排序的所有联系人列表。

例子：

get_contacts()

退货：

[
  {
    "address": "+15551234567",
    "name": "Emily Rothrock",
    "callCount": 45
  },
  {
    "address": "+15559876543",
    "name": "Heather",
    "callCount": 32
  }
]

通话记录字段

• id：唯一记录ID
• date：ISO呼叫时间戳
• duration：呼叫持续时间（秒）
• address：电话号码
• name：联系人姓名（如有）
• answered：呼叫是否应答
• outgoing：true=呼出，false=呼入
• read：是否读取了呼叫通知
• callType：1=常规通话，16=FaceTime
• uniqueId：呼叫的唯一标识符

隐私和安全

• 只读访问：只查询数据库，从不修改
• 本地数据：所有数据都保留在Mac上
• 无网络呼叫：没有数据发送到任何地方
• macOS权限：如果从某些应用程序运行，则需要完全磁盘访问权限

故障排除

“找不到数据库”错误

通话记录数据库应位于：

~/Library/Application Support/CallHistoryDB/CallHistory.storedata

验证它是否存在：

ls -la ~/Library/Application\ Support/CallHistoryDB/

未返回数据

• 检查iPhone是否与Mac同步（设置→ 电话→ 呼叫其他设备）
• 验证iPhone上的通话记录未被禁用

权限错误

• 为运行MCP服务器的应用程序授予全磁盘访问权限
• 对于Claude Code/iTerm2：系统设置→ 隐私和安全→ 全磁盘访问

发展

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode during development
npm run watch

技术细节

• 数据库：SQLite（更好的平方3）
• 时间戳转换：苹果核心数据时代（2001-01-01）→ISO 8601
• 查询性能：ZDATE字段上的索引查询
• MCP-SDK：@modelcontextprotocol/sdk^1.0.4

许可证

麻省理工学院

作者

丹尼尔·尚克林