146 lines
5.6 KiB
Markdown
146 lines
5.6 KiB
Markdown
# Plaud MCP Plugin for MPM
|
|
|
|
Connects Claude (CoWork / Claude desktop) to your Plaud recordings — list, search, transcripts, AI summaries, and meeting notes directly in CoWork.
|
|
|
|
**Version:** 0.1.2
|
|
**Author:** Message Point Media
|
|
**Repo:** [git.alwisp.com/jason/plaud-mpm-plugin](https://git.alwisp.com/jason/plaud-mpm-plugin)
|
|
|
|
---
|
|
|
|
## How Authentication Works
|
|
|
|
Plaud does not offer a public OAuth API. The plugin authenticates using the long-lived `authToken` JWT that the Plaud desktop app stores in Electron's encrypted `safeStorage` (Chromium v10 AES-128-CBC, key derived from the macOS login keychain).
|
|
|
|
### Token types
|
|
|
|
| Token | Lifetime | Source | Used by plugin |
|
|
|---|---|---|---|
|
|
| `authToken` | ~6 months | Electron safeStorage | ✅ Primary |
|
|
| `wrtToken` | ~30 days | Electron safeStorage | No |
|
|
| `wtToken` | ~24 hours | Plaud web browser | Legacy fallback |
|
|
|
|
### Resolution order
|
|
|
|
The server checks credentials in this order at every startup:
|
|
|
|
1. `PLAUD_TOKEN` environment variable (override)
|
|
2. `~/.plaud/tokens-mcp.json` → `access_token` field ← **normal path**
|
|
3. `~/.plaud/config.json` → `token` field (legacy 24-hour web token)
|
|
|
|
### How `tokens-mcp.json` gets written
|
|
|
|
Run `plaud_decrypt_tokens.py` (in the Claude CoWork folder). It:
|
|
|
|
1. Reads the Chromium encrypted token store from `~/Library/Application Support/Plaud/`
|
|
2. Derives the AES key from the macOS login keychain entry `Plaud Keys`
|
|
3. Decrypts the `authToken` JWT
|
|
4. Writes `~/.plaud/tokens-mcp.json` with `access_token` set to that JWT
|
|
|
|
### Why not OAuth?
|
|
|
|
Plaud's API sits behind Cloudflare with browser-fingerprint checks that block standard HTTP clients. The `authToken` from the desktop app bypasses this because it is a long-lived JWT accepted directly by `api.plaud.ai` without browser validation.
|
|
|
|
---
|
|
|
|
## Token Renewal
|
|
|
|
The `authToken` expires approximately every **6 months**. Current token expires: **~2026-11-25**.
|
|
|
|
**To renew:**
|
|
|
|
```bash
|
|
# From the Claude CoWork folder (or wherever plaud_decrypt_tokens.py lives):
|
|
cd ~/Library/CloudStorage/GoogleDrive-bryan@messagepoint.media/My\ Drive/Claude\ CoWork
|
|
python3 plaud_decrypt_tokens.py
|
|
```
|
|
|
|
This re-reads the Plaud desktop app's current token from Electron safeStorage and overwrites `~/.plaud/tokens-mcp.json`. The plugin picks it up automatically on next restart — no reinstall required.
|
|
|
|
**Prerequisites for renewal:**
|
|
- Plaud desktop app must be installed and you must be logged in
|
|
- Run the script while the desktop app is not actively running (or has been closed long enough for the keychain to be accessible)
|
|
- macOS only (the decryption uses the macOS login keychain)
|
|
|
|
**Verify the token is loaded:**
|
|
|
|
Ask Claude: *"check plaud connection"* — or use the `plaud_user_info` tool directly. It returns `token_loaded: true` if the token was found.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Plugin file (Claude CoWork)
|
|
|
|
The plugin ships as a `.plugin` zip archive. Install by dropping it into Claude CoWork's plugin manager:
|
|
|
|
```
|
|
Claude CoWork/plugins/plaud-mpm-v0.1.2.plugin
|
|
```
|
|
|
|
The `.dxt` extension (used by Claude desktop's extension system) is identical — same zip format, different extension.
|
|
|
|
### First-time setup
|
|
|
|
1. Install the Plaud desktop app and log in
|
|
2. Run `python3 plaud_decrypt_tokens.py` from the CoWork folder
|
|
3. Confirm `~/.plaud/tokens-mcp.json` was created
|
|
4. Install `plaud-mpm-v0.1.2.plugin` in Claude CoWork
|
|
5. Ask Claude *"list my recent Plaud recordings"* to verify
|
|
|
|
---
|
|
|
|
## Available Tools
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `plaud_list_recordings` | List recordings newest-first (limit, transcript filter) |
|
|
| `plaud_search_recordings` | Search by title and/or date range |
|
|
| `plaud_get_transcript` | Full transcript (polished → raw fallback) |
|
|
| `plaud_get_summary` | AI summary (`auto_sum_note` → outline fallback) |
|
|
| `plaud_get_notes` | All AI-generated note types from `content_list` |
|
|
| `plaud_get_recording_detail` | Full metadata including available content types |
|
|
| `plaud_user_info` | Connection status and token check |
|
|
|
|
### Summary content types
|
|
|
|
`plaud_get_summary` returns a `summary_type` field:
|
|
|
|
- `auto_sum_note` — rich AI meeting notes (Meeting Information, Meeting Notes, Next Arrangements, AI Suggestions). This is what appears in the Plaud web UI "Summary" tab.
|
|
- `outline` — timestamped topic list (fallback when AI summary is unavailable)
|
|
- `none` — no summary content available
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
.claude-plugin/plugin.json Plugin metadata
|
|
.mcp.json MCP server registration (uv runner)
|
|
server/plaud_mcp.py MCP server (FastMCP, stdio)
|
|
skills/plaud/SKILL.md Skill trigger rules for Claude
|
|
docs/SETUP.md Full setup and renewal guide
|
|
dist/plaud-mpm-v0.1.2.plugin Installable plugin package
|
|
```
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### 0.1.2 — 2026-05-12
|
|
- **Fix:** `plaud_get_summary` now checks `auto_sum_note` (rich AI meeting notes) before `outline`. Previously only returned the timestamped topic outline.
|
|
- **Fix:** Added `_fetch_s3_text()` helper — `auto_sum_note` content is HTML/Markdown, not JSON. The old `_fetch_s3_json()` call returned empty results.
|
|
- **Fix:** `plaud_get_recording_detail` `has_summary` now checks both `auto_sum_note` and `outline`.
|
|
- **Fix:** `plaud_get_notes` routes `auto_sum_note` through `_fetch_s3_text()` instead of `_fetch_s3_json()`.
|
|
- `plaud_get_summary` response now includes `summary_type` field.
|
|
- README and setup guide rewritten to reflect true auth process.
|
|
|
|
### 0.1.1 — 2026-05-12
|
|
- Added `_fetch_s3_text()` stub (incomplete — superseded by 0.1.2)
|
|
- README rewrite (first pass)
|
|
|
|
### 0.1.0 — 2026-05-11
|
|
- Initial release
|
|
- Token decryption via `plaud_decrypt_tokens.py`
|
|
- Tools: list, search, transcript, summary (outline only), notes, detail, user info
|