docs: add SETUP.md — true 6-month token process, renewal commands, troubleshooting
This commit is contained in:
+185
@@ -0,0 +1,185 @@
|
|||||||
|
# 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*
|
||||||
Reference in New Issue
Block a user