金大哥 - apple-voice-memo-mcp MCP 详情

article

README

🚀 Apple Voice Memo MCP 服务器

这是一个 MCP（模型上下文协议）服务器，可让你以编程方式访问 macOS 上的 Apple 语音备忘录。借助它，Claude 等 AI 助手就能与你的语音录音进行交互。

它与 whisper-mcp 配合使用，可实现本地转录。

🚀 快速开始

本服务器可让你通过编程方式访问 macOS 上的 Apple 语音备忘录，还能让 AI 助手与语音录音交互。

✨ 主要特性

列出语音备忘录 - 浏览所有语音备忘录及其元数据。
获取备忘录详情 - 获取特定录音的详细信息。
获取音频 - 访问音频文件路径或 Base64 编码的音频数据。
获取转录内容 - 从备忘录中提取转录内容（Apple 存储在音频文件中）。
转录备忘录 - 使用 Apple 的 SFSpeechRecognizer 生成转录内容。

📦 安装指南

npm install -g apple-voice-memo-mcp

或者直接使用 npx：

npx apple-voice-memo-mcp

📚 详细文档

配置

Claude Desktop

添加到你的 Claude Desktop 配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apple-voice-memo-mcp": {
      "command": "npx",
      "args": ["-y", "apple-voice-memo-mcp"]
    }
  }
}

编辑完成后，重启 Claude Desktop。

Claude Code (CLI)

对于 Claude Code，添加到项目的 .mcp.json 文件中：

{
  "mcpServers": {
    "apple-voice-memo-mcp": {
      "command": "npx",
      "args": ["-y", "apple-voice-memo-mcp"]
    }
  }
}

或者进行用户范围的配置，添加到 ~/.claude/settings.json 中：

{
  "mcpServers": {
    "apple-voice-memo-mcp": {
      "command": "npx",
      "args": ["-y", "apple-voice-memo-mcp"]
    }
  }
}

提示：在 Claude Code 中使用 /mcp 来验证服务器是否已连接。

本地开发设置

如果从源代码而不是 npm 运行：

{
  "mcpServers": {
    "apple-voice-memo-mcp": {
      "command": "node",
      "args": ["/path/to/apple-voice-memo-mcp/dist/index.js"]
    }
  }
}

权限

完全磁盘访问权限：读取语音备忘录数据库所需。
- 转到系统设置 > 隐私与安全 > 完全磁盘访问权限。
- 添加你的终端应用或 Claude Desktop。
语音识别权限（用于转录）：
- 仅在使用 transcribe_memo 工具时需要。
- 首次使用时系统会提示。

MCP 工具

`list_voice_memos`

列出所有带有元数据的语音备忘录。参数：

limit（可选）：最大结果数（1 - 100，默认值：50）
offset（可选）：分页偏移量
search（可选）：按标题过滤的搜索词

示例响应：

{
  "memos": [
    {
      "id": 1,
      "title": "会议记录",
      "date": "2025-01-07T10:30:00.000Z",
      "duration": 120.5,
      "hasTranscript": true
    }
  ],
  "total": 15
}

`get_voice_memo`

获取特定备忘录的详细元数据。参数：

id（必需）：备忘录 ID

`get_audio`

检索音频文件。参数：

id（必需）：备忘录 ID
format（可选）："path" 或 "base64"（默认值："path"）

`get_transcript`

从备忘录中提取转录内容。参数：

id（必需）：备忘录 ID
format（可选）："text"、"json" 或 "timestamped"

`transcribe_memo`

使用 SFSpeechRecognizer 转录备忘录。参数：

id（必需）：备忘录 ID
language（可选）：语言代码（默认值："en-US"）

工作原理

数据访问

语音备忘录数据存储在以下位置：

数据库：~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/CloudRecordings.db
音频文件：同一目录，.m4a 格式

转录内容存储

Apple 使用名为 tsrp 的自定义 MPEG - 4 原子将转录内容直接存储在 .m4a 音频文件中。此 MCP 服务器会解析这些原子以提取转录内容，不存在单独的转录文件。

开发

# 克隆仓库
git clone https://github.com/jwulff/apple-voice-memo-mcp.git
cd apple-voice-memo-mcp

# 安装依赖
npm install

# 构建
npm run build

# 在开发环境中运行
npm run dev

# 使用 MCP 检查器进行测试
npm run inspector

故障排除

"未找到语音备忘录数据库"

确保你至少打开过一次语音备忘录应用。
为你的终端/应用授予完全磁盘访问权限。
检查语音备忘录是否启用了 iCloud 同步。

"没有可用的转录内容"

在 macOS Sequoia+ 系统上，在语音备忘录应用中打开备忘录以触发自动转录。
较旧的 macOS 版本没有自动转录功能。
使用 transcribe_memo 工具通过 SFSpeechRecognizer 生成转录内容。

原生模块绑定错误

如果你看到有关缺少 better_sqlite3.node 绑定的错误：

npm rebuild better-sqlite3

这会为你当前的 Node.js 版本重新编译原生模块。

📄 许可证

本项目采用 MIT 许可证。

apple-voice-memo-mcp