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](https://www.plaud.ai/download) 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](https://www.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:

```bash
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

```bash
cat ~/.plaud/tokens-mcp.json
```

Should contain:
```json
{
  "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:
```json
{
  "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:**

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

4. **Verify** the new token was written:

```bash
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:

```bash
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:

```bash
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:

```json
{
  "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

```bash
# 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*