内容
# plaud-mcp
[](https://www.npmjs.com/package/@namraks-labs/plaud-mcp)
[](LICENSE)
一款本地 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于同步您的 [Plaud](https://www.plaud.ai) Note Pro / NotePin 记录 — AI 摘要、亮点和逐字记录 — 到纯 Markdown 文件在您的机器上，并将其暴露给像 Claude 这样的 MCP 客户端。
每个记录都成为一个 Markdown 文件，带有 YAML 前置信息，因此可以直接放入 Obsidian、一个笔记文件夹或任何读取 Markdown 的工具。同步是增量和幂等的。
> **注意：** Plaud 没有官方公共 API。此工具与 Plaud 网络应用使用的后端进行通信，是通过观察到的流量反向工程的（与 [plaud-sync-for-obsidian](https://github.com/leonardsellem/plaud-sync-for-obsidian) 插件相同的方法）。如果 Plaud 更改其后端，可能会在没有通知的情况下中断。请自行承担风险；此项目与 Plaud 无关。
## 目录
- [功能](#功能)
- [安装](#安装)
- [同步令牌](#同步令牌) — 请先阅读此部分；这是唯一麻烦的部分
- [用作 CLI](#用作-CLI)
- [与 Claude 结合使用](#与-Claude-结合使用) — Claude Code 和 Claude Desktop
- [与代理/自动化结合使用](#与代理/自动化结合使用) — 无头，定时
- [管理](#管理)
- [配置](#配置)
- [输出格式](#输出格式)
## 功能
- **MCP 服务器** — `plaud_sync`、`plaud_list`、`plaud_get_recording`、`plaud_transcribe`、`plaud_status` 工具通过 stdio。
- **CLI** — 终端中执行相同的操作，用于首次身份验证和定时同步。
- **按需转录** — 触发 Plaud 的云转录 + AI 摘要生成，适用于尚未处理的记录（而不仅仅是拉取已经处理的记录）。
- **Markdown 输出** — 每个记录一个文件：`summary`、`highlights` 和一个说话者-逐字记录的 `transcript`，带有前置信息（`plaud_file_id`、`title`、`date`、`duration_sec`、`language`）。
- **幂等** — 匹配由前置信息的 `plaud_file_id` 进行，因此重新同步是安全的，手动重命名文件不会创建重复项。
## 安装
```sh
# 一次性，无需安装
npx -y @namraks-labs/plaud-mcp --help
# 或克隆（npm 安装会自动运行构建）
git clone https://github.com/Namraks-Labs/plaud-mcp.git
cd plaud-mcp && npm install
```
## 同步令牌
Plaud 没有 API 密钥。身份验证是一个 **来自您登录会话的 JWT** — 这是设置中唯一麻烦的部分，因此值得做一次，仔细操作。
**获取令牌：**
1. 登录 [web.plaud.ai](https://web.plaud.ai)。
2. 打开开发者工具 → **网络** 标签。按您的 API 主机（例如 `api-euc1`）进行筛选。重新加载页面。
3. 点击任意请求 → **头部** → **请求头部** → 复制 `authorization: bearer ` 后的值（长 `eyJ…` 字符串）。
**设置令牌** — 三种方式，选择一种：
```sh
# 1. 保存到文件（chmod 600）。省略参数以从 stdin 读取并保持
# 它在 shell 历史记录之外 — 推荐：
pbpaste | plaud-mcp auth # macOS；或：plaud-mcp auth （然后在提示符下粘贴）
plaud-mcp auth eyJ… # 或直接传递它
# 2. 环境变量（适用于 MCP 客户端配置和 CI）：
export PLAUD_TOKEN=eyJ…
```
如果同时存在保存的文件和环境变量，则环境变量优先。
**区域：** 如果您的帐户不在默认的 `https://api.plaud.ai` 上，请设置您的主机一次（EU 帐户使用 `api-euc1`）：
```sh
plaud-mcp api https://api-euc1.plaud.ai
```
在开发者工具 → 控制台中找到您的主机：`localStorage.getItem("pld_plaud_user_api_domain")`。
**过期时间：** 令牌是一个真正的 JWT，具有 `exp` 声明 — 观察到的寿命约为 1 年。`plaud-mcp status` 解码它并告诉您剩余的天数。当它过期时，同步失败，出现明确的 `HTTP 401`；重复上述步骤以刷新它。
## 用作 CLI
```sh
plaud-mcp sync # 同步新记录（增量）
plaud-mcp sync --dry-run # 显示将同步的内容，不写入任何内容
plaud-mcp sync --force # 重新同步所有内容（覆盖文件 ID）
plaud-mcp list --limit 20 # 列出云端记录
plaud-mcp list --on 2026-05-26 # 按本地日期筛选（或 --since/--until 范围）
plaud-mcp list --title "standup" # 按记录名称筛选（子字符串，不区分大小写）
plaud-mcp transcribe <id> # 触发云转录 + AI 摘要，等待，写入 Markdown
plaud-mcp transcribe-all # 转录所有缺少转录/摘要的记录
plaud-mcp get <file-id> # 将一个记录的 Markdown 打印到 stdout
plaud-mcp status # 显示配置，令牌过期时间，最后一次同步时间戳
```
### 生成转录
`sync` 仅拉取 Plaud 已经 **转录** 的记录。要为尚未处理的记录启动转录 + AI 摘要生成（或重新运行它），请使用 `transcribe`:
```sh
plaud-mcp transcribe <file-id> --language sv # 瑞典语；使用 "auto" 让 Plaud 检测
plaud-mcp transcribe <file-id> --save # 还将结果保存回 Plaud 云
plaud-mcp transcribe <file-id> --no-start # 不要触发新作业，只需获取/渲染当前结果
plaud-mcp transcribe <file-id> --no-summary-wait # 在转录准备好时返回
```
这 **消耗您的 Plaud 转录配额** （与应用中按“转录”相同）。它触发作业，轮询直到完成，然后像 `sync` 一样写入 Markdown。在内部：`PATCH /file/{id}` 设置转录配置，`POST /ai/transsumm/{id}` 轮询结果，而 `--save` 通过 `PATCH /file/{id}` 将其写回。
**转录任务在 AI 摘要任务之前完成** ，因此默认情况下 `transcribe` 继续轮询直到摘要也可用。传递 `--no-summary-wait` 以在转录准备好时返回。默认情况下，结果还 **保存回 Plaud 云** （因此 Web 应用和 `sync` 看到它）；传递 `--no-save` 以仅保留本地。
要一次性处理所有尚未转录的内容：
```sh
plaud-mcp transcribe-all --dry-run # 预览将处理哪些记录
plaud-mcp transcribe-all # 转录所有记录（每个记录消耗配额）
plaud-mcp transcribe-all --limit 5 # 限制运行多少个
```
`transcribe-all` 针对每个缺少转录 **或** 摘要的记录（通过文件列表上的 `is_trans` / `is_summary` 标志检测）。
### 过滤（列表和转录全部）
`list` 和 `transcribe-all` 都接受相同的筛选器，因此您可以限定时间窗口和/或记录名称：
```sh
plaud-mcp list --since 2026-05-26 --until 2026-05-27 # 本地日期范围（包含）
plaud-mcp list --on 2026-05-26 # 单日快捷方式
plaud-mcp list --title "weekly sync" # 名称子字符串，不区分大小写
plaud-mcp transcribe-all --on 2026-05-26 --trigger-only # 仅转录那一天的记录
```
- **日期为本地时间** （记录的时区）和 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM`。 `--since`/`--until` 包含； `--on` 是两者快捷方式。
- **`--title`** 与 Plaud 存储的记录名称（应用内名称，或未命名记录的自动分配时间戳）匹配。注意列表不携带 AI 生成的标题 — 它位于每个记录的 Markdown 中，因此 grep 保险库按生成的标题搜索。
## 与 Claude 结合使用
服务器通过 stdio 运行。没有任何参数，`plaud-mcp` 启动 MCP 服务器。
### Claude Code
```sh
claude mcp add plaud \
-e PLAUD_API_DOMAIN=https://api-euc1.plaud.ai \
-e PLAUD_NOTES_DIR=$HOME/plaud-notes \
-- npx -y @namraks-labs/plaud-mcp
```
如果您已经运行了 `plaud-mcp auth`，则使用保存的令牌文件，您可以删除 `PLAUD_TOKEN`。否则，请添加 `-e PLAUD_TOKEN=eyJ…`。
### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"plaud": {
"command": "npx",
"args": ["-y", "@namraks-labs/plaud-mcp"],
"env": {
"PLAUD_TOKEN": "eyJ…",
"PLAUD_API_DOMAIN": "https://api-euc1.plaud.ai",
"PLAUD_NOTES_DIR": "/Users/you/plaud-notes"
}
}
}
}
```
公开的工具：
| 工具 | 描述 |
| --- | --- |
| `plaud_sync` | 将新记录拉入 Markdown 文件。参数：`force`、`limit`、`dryRun`。 |
| `plaud_list` | 列出云端记录而不同步。参数：`limit`、`since`、`until`、`titleContains`。 |
| `plaud_get_recording` | 通过 `fileId` 获取一个记录的渲染 Markdown，而不写入它。 |
| `plaud_transcribe` | 触发云转录 + AI 摘要获取记录，等待，写入 Markdown，并保存回云。参数：`fileId`、`language`、`summType`、`save`、`waitForSummary`、`timeoutSec`。消耗配额。 |
| `plaud_transcribe_all` | 转录每个缺少转录/摘要的记录。参数：`language`、`summType`、`limit`、`dryRun`、`save`、`triggerOnly`、`since`、`until`、`titleContains`。每个记录消耗配额 — 先使用 `dryRun`。 |
| `plaud_status` | 显示令牌源/过期时间，API 域，笔记/状态目录，最后一次同步。 |
## 与代理/自动化结合使用
CLI 子命令旨在无头驱动 — 通过 cron 作业，launchd 代理，systemd 计时器或自主编码代理。模式始终是：设置 `PLAUD_*` 环境变量，然后调用 `plaud-mcp sync`。
**通用无头同步：**
```sh
PLAUD_TOKEN=eyJ… \
PLAUD_API_DOMAIN=https://api-euc1.plaud.ai \
PLAUD_NOTES_DIR=$HOME/plaud-notes \
npx -y @namraks-labs/plaud-mcp sync
```
**cron（每小时）：**
```cron
0 * * * * PLAUD_NOTES_DIR=$HOME/plaud-notes /usr/local/bin/plaud-mcp sync >> $HOME/.plaud-mcp/logs/sync.log 2>&1
```
**macOS launchd** — 一个可编辑的代理位于 [`examples/launchd.plist`](examples/launchd.plist)。复制到 `~/Library/LaunchAgents/`，编辑路径/环境变量，然后：
```sh
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.example.plaud-mcp.plist
launchctl kickstart -p "gui/$(id -u)/com.example.plaud-mcp" # 立即运行一次
```
**systemd（Linux）** — 一个 `.service` + `.timer` 对位于 [`examples/systemd/`](examples/systemd/)。
对于自主代理，它需要的合约位于 [`AGENTS.md`](AGENTS.md)：如何认证，同步和诊断故障而无需人工干预。
## 管理
```sh
plaud-mcp status # 令牌源 + 剩余天数，API 域，最后同步，查看次数
```
- **令牌过期？** `status` 显示 `EXPIRED`，而 `sync` 以 `HTTP 401` 退出。重新提取 JWT（参见 [同步令牌](#同步令牌)）并重新运行 `plaud-mcp auth`。
- **速率限制？** `sync` 以 `HTTP 429` 退出。等待几分钟并重试。
- **从头开始重新同步？** 删除 `~/.plaud-mcp/state.json` 并运行 `plaud-mcp sync --force`。幂等 — 现有文件在原地覆盖，不重复。
- **定时作业静默？** 检查作业日志。健康空闲运行打印 `N total, 0 candidate(s)`。身份验证/网络故障在 stderr 上打印一行 `plaud-mcp: …`。
## 配置
环境变量覆盖保存的配置文件。
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `PLAUD_TOKEN` | — | JWT（`plaud-mcp auth` 的替代方案）。 |
| `PLAUD_API_DOMAIN` | `https://api.plaud.ai` | 您所在地区的 API 主机。 |
| `PLAUD_NOTES_DIR` | `~/plaud-notes` | Markdown 文件的输出目录。 |
| `PLAUD_STATE_DIR` | `~/.plaud-mcp` | 令牌，同步状态和配置存储的位置。 |
`PLAUD_STATE_DIR` 下的状态文件：
- `token` — JWT，`chmod 600`。
- `state.json` — `{ lastSyncMs, seenIds[] }` 用于增量同步。
- `config.json` — 保存的 API 域。
## 输出格式
```markdown
---
plaud_file_id: 286eea0e49fd44dfd7f704f52d9ee3d8
title: "Strategy meeting"
date: 2026-05-11T08:30:00.000Z
duration_sec: 2734
language: sv
source: plaud
---
# Strategy meeting
## Summary
…Plaud 的 AI 摘要…
## Highlights
- 关键点 1
- 关键点 2
## Transcript
**Speaker 1:** …
**Speaker 2:** …
```
文件写入 `PLAUD_NOTES_DIR/YYYY-MM-DD/<slug>-<id6>.md`，按记录开始日期分组。
## License
MIT © Namraks Labs
