# mcp-server-plaud

An MCP server that connects Claude to your [Plaud Note](https://www.plaud.ai) recordings, transcripts, and AI summaries via the unofficial Plaud web API.

## Quick Start

```bash
uvx mcp-server-plaud
```

## Get Your Plaud Token

The Plaud API uses a bearer token stored in your browser. To extract it:

1. Open Chrome and go to **https://web.plaud.ai**
2. Log in with your Plaud account
3. Press **F12** (or **Cmd+Option+I** on Mac) to open DevTools
4. Go to the **Application** tab → **Local Storage** → `https://web.plaud.ai`
5. Find the key that contains your bearer token — a long string starting with `eyJ...`
6. Copy the **full token value**

> **Important:** Include the `bearer ` prefix (with the space) when setting `PLAUD_TOKEN`.

## Claude Desktop Configuration

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "plaud": {
      "command": "uvx",
      "args": ["mcp-server-plaud"],
      "env": {
        "PLAUD_TOKEN": "bearer eyJ...your_token_here"
      }
    }
  }
}
```

## Claude Code Configuration

```bash
claude mcp add plaud -- uvx mcp-server-plaud
```

Then set your token as an environment variable or use a `.env` file (see below).

## Alternative: .env File

Instead of putting the token in your Claude config, you can create `~/.config/plaud/.env`:

```bash
mkdir -p ~/.config/plaud
echo 'PLAUD_TOKEN=bearer eyJ...your_token_here' > ~/.config/plaud/.env
```

The server searches for `.env` files in this order:
1. Current working directory
2. `~/.config/plaud/.env`
3. Package parent directory
4. `~/.claude/skills/plaud-transcripts/.env` (legacy)

## Available Tools

| Tool | Description |
|------|-------------|
| `plaud_list_recordings` | List all recordings with dates, durations, and IDs |
| `plaud_get_transcript` | Fetch the full transcript with speaker diarization |
| `plaud_get_summary` | Fetch the AI-generated summary |
| `plaud_get_recording_details` | Get everything: metadata, transcript, and summary |
| `plaud_search_recordings` | Search recordings by filename or keywords |
| `plaud_list_devices` | List connected Plaud Note devices |

## CLI Client

The package also includes a standalone CLI client:

```bash
# Install
uvx --from mcp-server-plaud plaud-client --help

# List recordings
uvx --from mcp-server-plaud plaud-client list

# Get full details for a recording
uvx --from mcp-server-plaud plaud-client details <file_id>

# Search recordings
uvx --from mcp-server-plaud plaud-client search "meeting topic"

# Export all transcripts to files
uvx --from mcp-server-plaud plaud-client export --output-dir ./exports

# List connected devices
uvx --from mcp-server-plaud plaud-client devices

# Test your connection
uvx --from mcp-server-plaud plaud-client test
```

## EU Users

If your Plaud account is on the EU region, set the API domain:

```
PLAUD_API_DOMAIN=https://api-euc1.plaud.ai
```

Add it to your `.env` file or pass it in the Claude Desktop `env` block.

## Token Expiry

Plaud tokens expire periodically. If you get 401 errors, re-extract the token from web.plaud.ai using the steps above.

## License

MIT
