Plaud MCP

A Humanly Labs open source project.

Bring your Plaud Note recordings into Claude Desktop. Search meetings, pull transcripts, and ask Claude about your notes — directly from chat.

Before you start, you'll need

A checklist. If you're missing any of these, the setup script will tell you and point you at how to get it — but it's faster to confirm now.

Setup — three commands, about 30 seconds

Open Terminal (Cmd+Space → type "Terminal" → Enter), then run these three commands one at a time:

git clone https://github.com/Humanly-Labs/plaud-mcp.git

cd plaud-mcp

./setup

That's it. The setup script does everything else. The rest of this section explains what's happening while it runs, so nothing surprises you.

What ./setup does, step by step

1. Pre-flight checks ✓ Confirms you have macOS, Python 3.9+, and Claude Desktop. If any of them are missing, the script stops with a clear instruction on how to get it.

2. Creates a Python virtual environment in .venv/ So this project's Python packages don't conflict with your system Python or other projects.

3. Installs dependencies from requirements.txt Three small Python packages: mcp[cli], python-dotenv, pydantic.

4. Signs you in to Plaud in your browser 🌐 A browser tab opens to web.plaud.ai/platform/oauth — sign in however you normally use Plaud (Google, Apple, passkey, email/password), then click Authorize on Plaud's consent screen. When you see the rainbow nyan-cat page, you're done — close the tab.

5. Registers Plaud with Claude Desktop Adds a plaud entry to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json). Any other MCP servers you have configured are left untouched. A timestamped backup is saved before any change.

6. Restarts Claude Desktop 🔄 The script quits and relaunches Claude Desktop so it picks up the new MCP server. macOS may ask "Terminal wants to control Claude" — click Allow. This is one-time and expected.

7. Verifies everything works ✓ Starts the MCP server in the background and confirms it responds to the same protocol Claude Desktop will use. If anything's wrong, you'll see a clear error.

When the script finishes, you'll see ✓ All set in your terminal. Open Claude Desktop and ask:

"List my recent Plaud recordings."

Claude should immediately respond with a list of your meetings.

Setup is safe to re-run

./setup is idempotent — running it a second time is a no-op. It detects you're already signed in, that the Claude Desktop entry already matches, and skips the restart. Re-run any time you want to verify everything is healthy.

What you can ask Claude

Once setup completes, Claude has access to your Plaud library. Try:

• "What did I discuss in my last meeting?"

• "Summarize my recordings from this week."

• "Search my Plaud for anything about [project name]."

• "Pull the transcript from [recording title]."

• "What action items did I commit to in the [meeting] call?"

Available Tools

CLI Commands

The same server.py powers both setup and the MCP server itself. From the plaud-mcp directory:

How It Works

The server uses Plaud's official OAuth 2 + PKCE developer flow — the same flow Plaud's own MCP package (@plaud-ai/mcp) uses:

1. --login opens web.plaud.ai/platform/oauth in your browser. You sign in however you normally do (Google, Apple, passkey, email/password) and click Authorize.

2. Plaud redirects back to a local callback. The server exchanges that for an access_token + refresh_token and caches them in .plaud_token.json next to server.py (mode 0600, ignored by git).

3. Before every API call, the server transparently refreshes the access token if it's within 60s of expiring. You never log in again unless you revoke access from your Plaud account.

API calls go to https://platform.plaud.ai/developer/api/open/third-party/* (Plaud's official developer API).

The OAuth client ID used is the public client baked into Plaud's own MCP bundle (client_9c501dad-…). This isn't a security backdoor — it's a public OAuth identifier intended for third-party clients. You can override it via PLAUD_OAUTH_CLIENT_ID in .env if Plaud ever rotates it.

Troubleshooting

./setup says Python 3.9+ is required Install a current Python with brew install python3 (Homebrew) or from python.org. Then re-run ./setup.

./setup says Claude Desktop isn't installed Download it from claude.ai/download, install, then re-run ./setup.

Setup completes but Claude says it doesn't have Plaud tools Quit Claude Desktop fully (Cmd+Q) and reopen it. Claude Desktop sometimes needs a moment to reconnect after MCP changes. If the problem persists, run python3 server.py --status to verify auth, then python3 server.py --install to re-register.

./setup says "OAuth login timed out" You probably closed the browser before clicking Authorize. Re-run ./setup. If the browser doesn't open automatically, copy the URL printed in your terminal into a browser manually.

./setup step 2 (Plaud sign-in) fails with an authorization error Plaud's Developer API requires a paid Plaud subscription (Pro or Unlimited). The free Starter tier doesn't currently include API access. Upgrade your Plaud account at plaud.ai/pricing, then re-run ./setup.

pip install fails with "externally-managed-environment" This shouldn't happen with ./setup since it uses a venv. If you're running pip manually, use the venv's pip: .venv/bin/pip install -r requirements.txt.

Wrong Plaud account is signed in Run python3 server.py --logout, then ./setup again.

"Permission denied" when running ./setup If you downloaded the repo as a .zip from GitHub (instead of cloning with git), macOS may have stripped the executable bit. Either run chmod +x setup once, or invoke it via bash directly: bash setup.

macOS asks for permission to control Claude Desktop This is normal and expected the first time setup runs on a new Mac. The dialog reads something like "Terminal wants access to control Claude." Click Allow. If you click Don't Allow by mistake, grant it manually in System Settings → Privacy & Security → Automation.

OAuth login: browser opens but callback never returns Some setups block the local callback URL (http://localhost:8199/auth/callback). Common causes:

• Brave browser with strict Shields. Disable Shields for localhost during setup.

• Little Snitch / Lulu / similar firewalls. Allow inbound connections on the local port.

• Active VPN routing localhost through the tunnel. Disconnect briefly during setup.

• Port 8199 in use. Set PLAUD_OAUTH_REDIRECT_PORT in .env to a free port and re-run setup.

Claude says "No Plaud recordings found" Your account has no recordings yet, or none have synced to Plaud's cloud. Make a recording with your Plaud Note device (or the Plaud mobile/web app), wait for it to sync, then try again. The MCP server only sees what's already in your Plaud account.

Tokens look stale / Claude returns auth errors Run python3 server.py --logout, then ./setup again.

Advanced

Manual setup (without ./setup)

If you'd rather not run a shell script, do these by hand from the plaud-mcp/ directory:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 server.py --login        # browser-based sign-in
python3 server.py --install      # register in Claude Desktop, restart prompt

Connecting other MCP clients

Claude Code

claude mcp add plaud -- /absolute/path/to/plaud-mcp/.venv/bin/python3 /absolute/path/to/plaud-mcp/server.py

Cursor / Windsurf / others

Point the MCP client at the venv's Python and server.py:

{
  "mcpServers": {
    "plaud": {
      "command": "/absolute/path/to/plaud-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/plaud-mcp/server.py"]
    }
  }
}

No env vars are required.

Configuration overrides

Optional environment variables, settable in .env:

Privacy and Security

• Runs 100% locally on your machine.

• Only network calls are to web.plaud.ai, platform.plaud.ai, and localhost. No third-party telemetry.

• OAuth tokens live in .plaud_token.json next to server.py — mode 0600, ignored by git, written atomically via tempfile.mkstemp + os.replace so there's never a window where the file is world-readable.

• --logout calls Plaud's revoke endpoint to invalidate the access token server-side, then deletes the local file.

• The cached refresh_token is a long-lived credential — treat it like a password. If you suspect it's been exfiltrated, run --logout and revoke the app from your Plaud account settings.

• JWT signatures are not verified locally; we only read the exp claim to decide when to refresh. Authorization decisions happen on Plaud's servers.

• Prompt-injection caveat: this server returns recording transcripts and summaries verbatim to the LLM. A recording could plausibly contain text that tries to manipulate the LLM. The tools here are read-only on recordings, so the blast radius is bounded — but be aware if you wire this into an agent with destructive tools.

Credits & History

This is a Humanly Labs open source project. We didn't start from scratch — we took an early Plaud-MCP scaffold and pushed it toward something anyone with a Mac can install in a single command. A nod of credit to the projects that came before:

• Initial release of this repository (March 2026, commit f207b2c) — authored by Brody Fausett at dbf100. Established the project scaffolding and the MCP tool surface that we kept and rebuilt around.

• @plaud-ai/mcp — Plaud's own official MCP package. We reuse its public OAuth client_id and follow the same platform.plaud.ai/developer/api/open/third-party/* endpoint conventions, which is why anything that works with Plaud's official MCP also works here.

• sergivalverde/plaud-toolkit and rggnkmp/plaud-connector — community reverse-engineering work that mapped out the OAuth + PKCE flow and gave us early reference for how Plaud's Basic-auth-with-empty-secret token exchange works.

What Humanly Labs added in this rewrite

• One-command setup — ./setup checks every prerequisite, creates a Python venv, installs dependencies, opens the browser for OAuth sign-in, registers with Claude Desktop (preserving every other MCP server you've configured), auto-restarts Claude Desktop, and runs a real end-to-end smoke test against the MCP protocol — all in about 30 seconds, from a clean clone, with zero manual config edits.

• Polished stdlib-only TUI — auto-detected ANSI colors with NO_COLOR respect, status icons, sectioned headings, aligned key/value rows, a nyan-cat browser callback after sign-in, and unknown CLI flags that surface help instead of silently launching the MCP server.

• OAuth flow rewrite — moved from the old short-lived consumer JWT to Plaud's official Developer OAuth (PKCE + refresh tokens) so users never re-paste tokens.

• Idempotent re-runs — re-running ./setup correctly detects existing state and doesn't restart Claude Desktop when nothing changed.

• Security hardening — atomic token writes with chmod 0600 from creation (no TOCTOU window), server-side /revoke call on logout, CSRF-safe OAuth callback handler that only responds to requests carrying the expected state, defensive URLError/OSError handling on every network call, HTML-escaped error rendering.

• Empty-library handling — if your Plaud account has no recordings yet, the tools return a helpful hint instead of a confusing empty array.

• Comprehensive documentation — explicit prerequisites checklist, step-by-step setup walkthrough, 12-entry troubleshooting section, transparent disclosure of the paid-tier Plaud requirement.

If you maintain one of the upstream projects above and want a different form of attribution, please open an issue.

Contributing

PRs welcome. The codebase is one file (server.py) on purpose — keep it that way unless there's a clear reason to split.

License

MIT — use it however you want.