# Plaud Mcp

> An MCP server for Plaud.ai

- **Type:** MCP server
- **Install:** `agentstack add mcp-charathram-plaud-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [charathram](https://agentstack.voostack.com/s/charathram)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [charathram](https://github.com/charathram)
- **Source:** https://github.com/charathram/plaud-mcp

## Install

```sh
agentstack add mcp-charathram-plaud-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# plaud-mcp

An MCP (Model Context Protocol) server for the [Plaud](https://web.plaud.ai) audio recording platform. Exposes Plaud's API as MCP tools, allowing AI assistants like Claude to list recordings, fetch transcripts and summaries, rename files, manage folders, and more.

Built with [Bun](https://bun.sh) + TypeScript. Compiles to a single native binary for Linux, macOS, and Windows.

## Features

- **15 MCP tools** covering the full Plaud API surface
- **Browser-based login** — no manual token extraction needed
- **Cross-platform binaries** — single-file executables, no runtime dependencies
- **Stdio transport** — works with any MCP-compatible client

### Available Tools

| Tool | Description |
|------|-------------|
| `plaud_list_files` | List all recordings, optionally filtered by transcription status or minimum duration |
| `plaud_get_file` | Get a single file's full `/file/detail` payload — metadata, content links, pre-fetched summary content, speaker embeddings, and pre-signed download URLs. Use `plaud_get_metadata` if you only need metadata. |
| `plaud_get_metadata` | Fetch metadata only for one or more files by id (live or trashed). Returns `{ found, missing }`. No transcript, summary, content links, or embeddings. |
| `plaud_search_files` | Search recordings by keyword or date range |
| `plaud_get_transcript` | Fetch raw or polished transcript text |
| `plaud_get_summary` | Fetch AI-generated summary |
| `plaud_export_transcript` | Export transcript as formatted TXT or SRT with optional timestamps/speakers |
| `plaud_rename_file` | Rename a single file |
| `plaud_batch_rename` | Rename multiple files at once (rate-limited) |
| `plaud_move_to_folder` | Move a file to a folder |
| `plaud_list_folders` | List all folders/tags |
| `plaud_trash_file` | Move a file to trash |
| `plaud_generate` | Generate transcript and summary for a file (auto or custom options) |
| `plaud_name_speakers` | Rename speakers in a transcript (e.g. "Speaker 2" to "Alice") |
| `plaud_get_user` | Get current user profile |

#### `plaud_get_file` response detail

In addition to core file metadata (`file_id`, `file_name`, `duration`, etc.) and the `content_list` of transcript/summary references, `plaud_get_file` surfaces the enriched fields that Plaud's `/file/detail/{id}` endpoint returns:

- `extra_data.aiContentHeader` — headline, category, language, keywords, recommended questions, and the template used to generate the summary
- `extra_data.tranConfig` — transcription configuration (language, LLM, diarization, summary template)
- `extra_data.model`, `extra_data.task_id_info`, `extra_data.last_trans_*` — model and task identifiers from the most recent transcription
- `pre_download_content_list` — summary content already fetched server-side, keyed by `data_id`, avoiding a follow-up S3 round trip
- `download_path_mapping` — pre-signed S3 URLs for assets like summary poster images
- `embeddings` — 256-dim speaker voice fingerprints keyed by speaker label
- `content_list[i].extra` — per-item metadata (task IDs for transcript/outline items, template info for summary items)

The shape of these fields is captured in `src/schemas.ts` (Zod schemas with `.passthrough()`, so any further additions from the Plaud API flow through unchanged).

#### `plaud_get_metadata` response detail

`plaud_get_metadata` resolves ids by hitting `/file/simple/web` (live recordings) and `/file/simple/web?is_trash=1` (trashed recordings) in parallel and merging the results, since the default list endpoint excludes trashed files. Each returned file carries the full per-file metadata block from the list endpoint: `id`, `filename`, `fullname`, `filetype`, `filesize`, `file_md5`, `duration`, `start_time`, `end_time`, `edit_time`, `edit_from`, `version`, `version_ms`, `timezone`, `zonemins`, `scene`, `serial_number`, `is_trans`, `is_summary`, `is_markmemo`, `is_trash`, `ori_ready`, `wait_pull`, `filetag_id_list`, and `keywords`. Ids that don't match any live or trashed recording are reported in the `missing` array.

---

## Install for Claude Desktop (.mcpb)

The quickest path on macOS (Apple Silicon) and Windows (x64). No terminal required. (Claude Desktop isn't available on Linux — Linux users should use the manual binary + JSON-config setup below.)

1. **Download** the `.mcpb` for your platform from the latest release and double-click it. Claude Desktop opens an install dialog.

   | Platform | File |
   |---|---|
   | macOS Apple Silicon | `plaud-mcp-v-darwin-arm64.mcpb` |
   | Windows x64 | `plaud-mcp-v-win32-x64.mcpb` |

2. Leave `Log Level` at `info` and click **Install**.

3. Open Claude and ask it to **"sign me into Plaud."** Claude calls the `plaud_login` tool, which opens a browser window. Sign in to Plaud normally; credentials are captured automatically and saved locally.

   | Platform | Credentials path |
   |---|---|
   | macOS / Linux | `~/.plaud-mcp/credentials.json` (mode 600) |
   | Windows | `C:\Users\\.plaud-mcp\credentials.json` (user-profile ACL) |

> On macOS, the first time `plaud_login` runs the OS may ask Claude Desktop for permission to control your browser ("Automation" permission). Click Allow.
>
> On Intel Macs, build from source (see below) — there's no prebuilt `darwin-x64` MCPB.

---

## Usage

### Prerequisites

- A supported browser for the login flow: Chrome, Chromium, Brave, Edge, Firefox, or any Chromium-based browser. Safari is not supported.
- Pre-built binary for your platform (see [Releases](../../releases)), **or** [Bun](https://bun.sh) v1.3+ if building from source

### 1. Download the binary

Download the binary for your platform from the latest release:

| Directory | Platform |
|-----------|----------|
| `linux-x64/plaud-mcp` | Linux x86_64 |
| `linux-arm64/plaud-mcp` | Linux ARM64 |
| `darwin-x64/plaud-mcp` | macOS Intel |
| `darwin-arm64/plaud-mcp` | macOS Apple Silicon |
| `windows-x64/plaud-mcp.exe` | Windows x86_64 |

Make the binary executable (Linux/macOS):

```bash
chmod +x plaud-mcp
```

**macOS users:** If you see a "damaged and can't be opened" error, remove the quarantine attribute:

```bash
xattr -d com.apple.quarantine plaud-mcp
```

### 2. Login

Run the login command:

```bash
./plaud-mcp --login
```

This opens your browser to web.plaud.ai. Sign in normally — auth credentials are captured automatically and saved to `~/.plaud-mcp/credentials.json` (mode 600 on POSIX). To save to a custom location, set `PLAUD_CREDENTIALS_FILE=/custom/path/credentials.json` before running.

Chrome, Chromium, Brave, Edge, and Firefox are auto-detected on Linux, macOS, and Windows. For other browsers, pass `--browser /path/to/browser`.

**Non-US accounts:** Plaud serves regional API endpoints (e.g. `https://api-euc1.plaud.ai` for EU, `https://api-apac1.plaud.ai` for APAC). The login flow auto-detects which one your account uses, but the server still needs to know where to call — set `PLAUD_API_BASE_URL` in your environment (or pass `--base-url ` on launch). The default is `https://api.plaud.ai`.

### 3. Configure Claude Code

The server looks for credentials in this order: `~/.plaud-mcp/credentials.json` (written by `--login`), then `PLAUD_AUTH_TOKEN` etc. as environment variables, then a `.env` file (`--env` flag, then `PLAUD_ENV_FILE` env var, then `.env` in cwd).

Pick one of the following:

**Option A — CLI (quickest):**

```bash
claude mcp add plaud -- /path/to/plaud-mcp --env /path/to/.env
```

**Option B — Project config** (shared with team via `.mcp.json`):

```json
{
  "mcpServers": {
    "plaud": {
      "command": "/path/to/plaud-mcp",
      "args": ["--env", "/path/to/.env"]
    }
  }
}
```

**Option C — Personal config** (all projects via `~/.claude.json`):

```json
{
  "mcpServers": {
    "plaud": {
      "command": "/path/to/plaud-mcp",
      "env": {
        "PLAUD_ENV_FILE": "/path/to/.env"
      }
    }
  }
}
```

Restart Claude Code for the MCP server to connect.

### CLI Options

| Flag | Description | Applies to |
|------|-------------|------------|
| `--env ` | Path to `.env` credentials file | login, server |
| `--base-url ` | Plaud API base URL (e.g. `https://api-euc1.plaud.ai` for EU). Default: `https://api.plaud.ai` | server |
| `--browser ` | Path to browser binary | login |
| `--log-level ` | Set log verbosity: `debug`, `info`, `warn`, `error` (default: `info`) | server |

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PLAUD_ENV_FILE` | Path to `.env` file with credentials (overridden by `--env`) | `.env` in current directory |
| `PLAUD_API_BASE_URL` | Plaud API base URL — set this if your account is in a non-US region (overridden by `--base-url`) | `https://api.plaud.ai` |
| `CHROME_PATH` | Path to browser binary (overridden by `--browser`) | Auto-detected |
| `PLAUD_LOG_LEVEL` | Log verbosity (overridden by `--log-level`) | `info` |

---

## Development

### Setup

```bash
bun install
```

### Login (dev mode)

```bash
bun run login
```

Or specify a browser via `CHROME_PATH`:

```bash
CHROME_PATH=/usr/bin/brave-browser bun run login
```

### Run the server

```bash
bun run start
```

### Configure Claude Code (dev mode)

```json
{
  "mcpServers": {
    "plaud": {
      "command": "bun",
      "args": ["run", "/path/to/plaud-mcp/src/index.ts"],
      "env": {
        "PLAUD_ENV_FILE": "/path/to/plaud-mcp/.env"
      }
    }
  }
}
```

### Run tests

```bash
bun test
```

Tests mock all HTTP requests and cover the API client, every tool handler, and MCP server integration.

### Build binaries

```bash
bash build.sh
```

Produces cross-platform binaries in `dist/`.

### Releasing

Bump the version, push the tag, and let CI handle the rest:

```bash
npm version patch    # or minor/major — bumps package.json and creates a v* git tag
git push --follow-tags
```

This triggers the CI pipeline which runs tests, builds all 5 platform binaries, and creates a GitHub release with auto-generated release notes and the binaries attached.

### Project Structure

```
src/
├── index.ts              # MCP server entry point, tool registration
├── client.ts             # Plaud API HTTP client with auth and Zod validation
├── env.ts                # Shared .env path resolution (--env, PLAUD_ENV_FILE, cwd)
├── logger.ts             # Colored logging with configurable levels
├── login.ts              # Browser-based login flow (puppeteer-core)
├── schemas.ts            # Zod schemas for API responses (runtime validation + types)
└── tools/
    ├── files.ts          # list_files, get_file, search_files, get_user
    ├── content.ts        # get_transcript, get_summary, export_transcript
    ├── mutations.ts      # rename, batch_rename, move_to_folder, trash, generate, name_speakers
    └── folders.ts        # list_folders
scripts/
└── dump-api.ts           # Dump raw API responses for schema discovery
test/
├── setup.ts              # Test helpers and fetch mocks
├── cli.test.ts
├── client.test.ts
├── files.test.ts
├── content.test.ts
├── mutations.test.ts
├── folders.test.ts
├── login.test.ts
└── server.test.ts
```

## License

[MIT](LICENSE) — Charathram Ranganathan

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [charathram](https://github.com/charathram)
- **Source:** [charathram/plaud-mcp](https://github.com/charathram/plaud-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-charathram-plaud-mcp
- Seller: https://agentstack.voostack.com/s/charathram
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.