Bridge your Plaud recordings into AI assistants via a Python CLI and an MCP server.
Alpha software. This project is pre-1.0. APIs, tool names, and CLI flags may change between minor versions. Pin a known-good version in production wiring and review the CHANGELOG before upgrading.
Unofficial — not affiliated with Plaud. The Plaud API is reverse-engineered from the Plaud web app. "Plaud" is a trademark of Plaud Inc.; this project is not affiliated with, endorsed by, or sponsored by Plaud. Use at your own risk: Plaud's Terms of Service may restrict reverse-engineering and automated access, and your account could be rate-limited or suspended. You still need a real Plaud account; this package does not replace the Plaud mobile or web apps.
From PyPI:
pip install plaud-tools
Windows users can also grab a bundled tray app + frozen CLI + MCP server from the latest release (no Python install required). See docs/INSTALL.md for the full walkthrough.
# Sign in once. Region is `us` or `eu`; auto-detected on first API call.
plaud-tools login --email you@example.com --region us
# Recent recordings
plaud-tools list
# Full detail for one recording (title, date, duration, headline)
plaud-tools show <recording-id>
The CLI ships as both plaud-tools and the shorter alias pt. Run
plaud-tools --help for the full subcommand list.
Log in via the CLI before starting the AI client; the MCP server reads the saved session automatically.
Claude Desktop — add to claude_desktop_config.json (Windows:
%APPDATA%\Claude\claude_desktop_config.json; macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"plaud": {
"command": "plaud-mcp"
}
}
}Claude Code — same JSON block, in ~/.claude.json (user-level) or
.claude.json at the project root.
Codex CLI — in ~/.codex/config.toml:
[mcp_servers.plaud]
command = "plaud-mcp"Fully quit and relaunch the AI client after editing the config — MCP servers are loaded once at startup. Full wiring details, troubleshooting, and tray bundle install steps live in docs/INSTALL.md.
| Entry point | What it is |
|---|---|
plaud-tools / pt |
Python CLI — list, search, transcribe, upload, rename, trash, merge recordings |
plaud-mcp |
MCP server (stdio transport) — exposes the tool surface below to AI clients |
plaud-tray (optional, pip install plaud-tools[tray]) |
Windows system-tray app for one-click sign-in and MCP wiring |
The MCP server exposes 7 workflow-oriented tools (canonical list in
src/plaud_tools/server.py):
| Tool | What it does |
|---|---|
browse_recordings |
List and filter recordings by date, title, folder |
get_recording |
Full detail for one recording; opt in to transcript / speakers / summary |
mutate_recording |
Rename, trash, restore, delete, move to folder, rename speaker |
upload_recording |
Upload a local audio file (transcodes via ffmpeg if needed) |
process_recording |
Trigger transcription + summarization; block until both complete |
list_folders |
List Plaud folders (id, name, color, icon) |
merge_recordings |
Merge two or more recordings into a single new recording |
git clone https://github.com/massive-value/plaud-tools.git
cd plaud-tools
pip install -e ".[dev]"
pytest -q
See CONTRIBUTING.md for the full contributor workflow,
including the PLAUD_LIVE_READS=1 live-test gate.
Plaud JWTs last ~300 days; plaud-tools auto-refreshes silently when the
token is within 30 days of expiry. Sessions are stored in the OS keyring when
available, with a mode-600 fallback at
~/.config/plaud-tools/session.json.
- docs/INSTALL.md — install + AI-client wiring walkthrough
- CONTRIBUTING.md — dev setup, testing, PR workflow
- SECURITY.md — security policy and vulnerability disclosure
- CHANGELOG.md — release notes
- LICENSE — LGPL-3.0-or-later