plaud-mpm-plugin/docs/SETUP.md

Plaud MCP Plugin — Setup & Renewal Guide

Version: 0.1.2
Last updated: 2026-05-12

This guide covers everything needed to set up the Plaud MCP plugin and keep it running. The old docx guide is superseded by this file.

---

Prerequisites

• macOS (token decryption uses the macOS login keychain)
• Plaud desktop app installed and logged in
• Python 3.10+
• uv installed (brew install uv or pip install uv)
• Access to the Claude CoWork folder

---

How the Token Works

The Plaud desktop app (Electron) stores a long-lived authToken JWT in the macOS keychain via Chromium's safeStorage API. This token is valid for approximately 6 months and is the only reliable way to authenticate with the Plaud API from a script.

There is no public OAuth flow. Web-based tokens (wtToken) expire in 24 hours and are not practical for an MCP server.

Token file: ~/.plaud/tokens-mcp.json
Field used: access_token
Current expiry: approximately 2026-11-25

---

First-Time Setup

Step 1 — Ensure Plaud desktop app is installed and logged in

Download from plaud.ai/download. Log in with your Plaud account. Let the app sync at least once so the token is written to the keychain.

Step 2 — Run the token extraction script

From the Claude CoWork folder:

cd ~/Library/CloudStorage/GoogleDrive-bryan@messagepoint.media/My\ Drive/Claude\ CoWork
python3 plaud_decrypt_tokens.py

Expected output:

✅ Token written to /Users/<you>/.plaud/tokens-mcp.json
   access_token: eyJ... (truncated)
   Expires: ~2026-11-25 (estimated)

If you see an error about the keychain, make sure the Plaud desktop app has been run at least once while logged in, then try again.

Step 3 — Verify the token file

cat ~/.plaud/tokens-mcp.json

Should contain:

{
  "access_token": "eyJ..."
}

Step 4 — Install the plugin in Claude CoWork

Drop plaud-mpm-v0.1.2.plugin into Claude CoWork's plugin manager (Settings → Plugins → Install from file). The .plugin and .dxt files are identical zip archives — use whichever extension your Claude version accepts.

Step 5 — Verify the connection

In Claude CoWork, ask: "check my Plaud connection"

Or trigger plaud_user_info directly. You should see:

{
  "region": "us",
  "api_base": "https://api.plaud.ai",
  "token_loaded": true
}

---

Token Renewal

Renew the token when it expires (~every 6 months) or if you see token_loaded: false or API auth errors.

Renewal steps

1. Open the Plaud desktop app and make sure you are logged in. The app refreshes its internal token on login.

2. Close the Plaud desktop app (quit it fully — not just minimize). This ensures the keychain entry is accessible.

3. Run the decryption script:

cd ~/Library/CloudStorage/GoogleDrive-bryan@messagepoint.media/My\ Drive/Claude\ CoWork
python3 plaud_decrypt_tokens.py

4. Verify the new token was written:

cat ~/.plaud/tokens-mcp.json

5. Restart Claude (or reload the plugin) so the MCP server picks up the new token.

No reinstall of the plugin is required — the server reads tokens-mcp.json fresh on every startup.

---

Environment Variable Override

If you need to use a specific token without running the decryption script:

export PLAUD_TOKEN="eyJ..."

Set this in ~/.zshrc or your shell profile if you want it to persist. The environment variable takes priority over tokens-mcp.json.

---

Region Configuration

The plugin defaults to the US API (api.plaud.ai). For EU accounts:

export PLAUD_REGION=eu

This switches the base URL to api.plaud.eu. Set in the .mcp.json env block if you want it permanent:

{
  "mcpServers": {
    "plaud-mpm": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "${CLAUDE_PLUGIN_ROOT}/server/plaud_mcp.py"],
      "env": {
        "PLAUD_REGION": "eu"
      }
    }
  }
}

---

Troubleshooting

token_loaded: false

The token file is missing or empty. Run plaud_decrypt_tokens.py to regenerate it.

invalid auth header / API returning status -3900

The token has expired. Follow the renewal steps above.

Plaud Keys not found in keychain

The Plaud desktop app hasn't been run on this machine, or was installed under a different user account. Log in to the desktop app, let it sync, then try the script again.

curl exit 22 errors when fetching recordings

Usually an auth issue — verify token_loaded: true first. If token is loaded but you still get 22, the API may have rate-limited the request; wait 30 seconds and retry.

Plugin shows as Plaud_MCP vs plaud-mpm

Two registrations exist: the .dxt extension installs as Plaud_MCP; the .plugin file installs as plaud-mpm. Both use the same plaud_mcp.py server. Use whichever is currently active — they are functionally identical once running v0.1.2.

---

Uninstall / Clean Up

# Remove token files
rm -rf ~/.plaud

# Remove plugin from CoWork via Settings → Plugins → Remove

---

Setup guide for Plaud MCP Plugin v0.1.2 — Message Point Media