plaud-mpm-plugin/README.md

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

---

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:

# 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