Metadata-Version: 2.4
Name: plaud-tools
Version: 0.8.2
Summary: Python rewrite for Plaud CLI and MCP workflows.
Author-email: massive-value <dev.bluehorizon@gmail.com>
License-Expression: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/massive-value/plaud-tools
Project-URL: Repository, https://github.com/massive-value/plaud-tools
Project-URL: Issues, https://github.com/massive-value/plaud-tools/issues
Project-URL: Changelog, https://github.com/massive-value/plaud-tools/blob/master/CHANGELOG.md
Keywords: plaud,mcp,cli,transcription,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: keyring<26,>=25
Requires-Dist: mcp<3.0,>=2.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: tomlkit>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: pyinstaller>=6; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: mcp[cli]<3.0,>=2.0; extra == "dev"
Provides-Extra: tray
Requires-Dist: pystray>=0.19; extra == "tray"
Requires-Dist: Pillow>=10; extra == "tray"
Requires-Dist: sv-ttk>=2.6; extra == "tray"
Requires-Dist: comtypes>=1.4; extra == "tray"
Requires-Dist: psutil>=5.9; extra == "tray"
Dynamic: license-file

# plaud-tools

**Talk to your Plaud recordings.** Connect your Plaud account to Claude (or another AI assistant) so you can ask questions about your meetings, generate summaries, and search across every recording — in plain English.

**What you can do:**
- Ask things like *"Summarize my client call from Tuesday afternoon."*
- Ask things like *"What did we decide about the Henderson account in last week's meeting?"*
- Drop an audio file into the chat and say *"Upload and transcribe this."*

Windows users get a one-click installer with auto-updates. macOS and Linux users can install via pip — see [docs/INSTALL-METHODS.md](docs/INSTALL-METHODS.md).

## Quickstart

**1. Open PowerShell.** Press the Windows key, type `PowerShell`, and press Enter. A blue window opens.

**2. Paste this command and press Enter:**

```powershell
irm https://raw.githubusercontent.com/massive-value/plaud-tools/main/scripts/install.ps1 | iex
```

This downloads PlaudTools from GitHub to your user folder. No admin rights are needed and nothing is installed system-wide.

**3. Sign in.** When the install finishes, a Windows notification appears saying *"PlaudTools is now running in your system tray — click the icon to sign in."* Click the PlaudTools icon in your taskbar (bottom-right, next to the clock — you may need to click the up-arrow `^` to find it). A sign-in window opens. Enter your Plaud email and password.

> **Signed up for Plaud with Google?** You don't have a Plaud password yet. Visit [web.plaud.ai](https://web.plaud.ai), click "Forgot password," and Plaud will email you a reset link — even though you've never set a password before. Use that new password here.

**4. Connect the apps you use.** After sign-in, the PlaudTools window opens. Click **Configure AI Agents…**, then click **Connect** next to each AI app you have installed (Claude Desktop, Claude Code, or Codex). Apps you don't have installed are shown as **Not installed** and can't be connected.

**5. Restart the apps you connected.** New connections only load on a fresh start.

- **Claude Desktop** — go to **File → Exit** (closing the window keeps it running in the tray), then reopen it from the Start menu.
- **Claude Code** — in your existing session, type `/exit`, then run `claude` again in a new terminal.
- **Codex** — press `Ctrl+C` to end the session, then run `codex` again in a new terminal.

**6. Try it.** In your AI assistant, paste this prompt:

```text
I just installed an MCP for Plaud. Can you take a look and make sure
everything is wired up. As an example, can you tell me about my most
recent meeting that has a summary. After that, tell me about what sort
of things you can do with the plaud tools and some potential ways that
it can apply to my workflows.
```

The assistant will confirm the tools are wired up, walk through one of your recent recordings, and explain what else it can do for you.

## Keeping PlaudTools up to date

PlaudTools checks GitHub for new releases once a day and notifies you when one is available.

### Installing an update

When an update is ready, you'll see an **Update available: vX.X.X** item at the top of the tray menu. Click it, then click **Install update and restart**. PlaudTools downloads the new version, swaps it in, and relaunches — usually under 30 seconds. Your sign-in and connected apps carry over.

### Checking your version

Click the PlaudTools icon in your taskbar to open the home window. Your current version is shown in the footer.

### If something goes wrong

Re-run the install command in PowerShell with **`-Repair`**:

```powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/massive-value/plaud-tools/main/scripts/install.ps1))) -Repair
```

This shuts down PlaudTools, wipes the install folder, and reinstalls the latest release. Your sign-in is preserved.

## Uninstalling

Open the tray menu, click **Uninstall…**, review the checklist, and click **Uninstall**. Your saved sign-in and log files are kept by default, so a future reinstall picks up where you left off.

## What PlaudTools can do

PlaudTools gives your AI assistant a set of tools for working with your Plaud account. You don't call these directly — you ask in plain English, and the assistant picks the right one.

| What it does | What you'd ask |
|---|---|
| Find recordings | *"Show me my recordings from last week."* |
| Read a recording | *"What did I say in the Henderson meeting?"* |
| Rename, move, or trash | *"Rename yesterday's 9am recording to 'Tax planning call'."* |
| Fix a transcript or summary | *"Fix the spelling of the client's name in yesterday's summary."* |
| Upload audio | *"Upload this audio file and transcribe it."* (with attachment) |
| Transcribe and summarize | *"Transcribe and summarize yesterday's recording."* |
| List and manage folders | *"Create a 'Client Calls' folder"* / *"What folders do I have in Plaud?"* |
| Merge recordings | *"Merge these three call segments into one recording."* |
| Download the audio | *"Save the audio from yesterday's client call."* |

## How this compares to Plaud's official MCP & CLI

Plaud now ships its own MCP server and CLI (`@plaud-ai/mcp`, `@plaud-ai/cli`). They're solid, and if all you need is to *read* your recordings, they're the safer choice — official, supported, and OAuth-based. Install them with `npx -y @plaud-ai/mcp@latest install`.

**They are read-only.** The official developer API behind them exposes three endpoints — list recordings, get one recording, get the current user. There are no write endpoints, so the official tools cannot change anything in your Plaud account. That's the difference between the two projects, and it isn't a gap that closes with their next release.

PlaudTools drives Plaud's web API instead, which is how it can write. 7 of our 11 tools have no official equivalent:

| | PlaudTools | Official |
|---|---|---|
| Browse, read transcripts, read summaries | ✅ | ✅ |
| Rename recordings | ✅ | ❌ |
| Trash / restore / permanently delete | ✅ | ❌ |
| Folders — list, create, edit, delete, move into | ✅ | ❌ |
| Name speakers in a transcript | ✅ | ❌ |
| Fix transcript text (find-and-replace) | ✅ | ❌ |
| Edit AI summaries | ✅ | ❌ |
| Upload local audio (auto-transcoded) | ✅ | ❌ |
| Download original audio | ✅ | ✅ |
| Trigger transcription / summarization | ✅ | ❌ |
| Merge recordings | ✅ | ❌ |
| Browse trash | ✅ | ❌ |
| Batch operations | ✅ | ❌ |
| Search your whole library | ✅ | ⚠️ newest 500 recordings only |
| Runs entirely on your machine | ✅ | ⚠️ HTTP mode routes recordings through Plaud's US server |
| Usage telemetry | none | sent on every tool call |
| Windows tray app, one-click install, auto-update | ✅ | ❌ npm only |

The two can coexist — nothing stops you connecting both and letting your assistant use whichever fits the request.

**The tradeoff:** because PlaudTools uses the private web API rather than the official one, it can break when Plaud changes that API, and it sits in a grey area of their Terms of Service (see the note at the bottom). The official tools don't have either problem. Pick accordingly.

A detailed feature-by-feature audit lives in [docs/plans/2026-07-31-official-plaud-mcp-cli-competitive-audit.md](docs/plans/2026-07-31-official-plaud-mcp-cli-competitive-audit.md).

## Other ways to install

The Windows tray bundle above is the recommended path for most users. Two other install methods exist:

- **PyPI** — if you have Python 3.11+, run `pip install plaud-tools`. You'll get the `plaud-tools` CLI and `plaud-mcp` server but no tray app or auto-updates.
- **Manual zip** — download `PlaudTools.zip` from the [latest GitHub release](https://github.com/massive-value/plaud-tools/releases/latest) and unzip anywhere. Useful for air-gapped machines or restrictive IT environments.

Full instructions for both: [docs/INSTALL-METHODS.md](docs/INSTALL-METHODS.md).

## Signing in again later

Your Plaud sign-in is good for about 30 days. Starting 5 days before it expires, the tray menu shows **Session expires in N days — sign in again** — click it and re-enter your password. If you wait until it fully expires, your AI assistant will tell you it can't reach Plaud; open the tray menu, click **Sign in…**, and you're back.

## Troubleshooting

**Claude (or your AI assistant) says it can't see Plaud after you wired it up.**
The connection only loads on a fresh start. Fully quit the app first — see step 5 of the Quickstart for the right way to do it on each platform — then reopen and try again.

**The PlaudTools icon isn't in your taskbar.**
Click the small up-arrow (`^`) next to the clock in the bottom-right of your taskbar — Windows hides newly-installed tray icons there by default. If you still don't see it, re-run the install command in PowerShell with `-Repair` (see "If something goes wrong" above).

Everything else — ffmpeg setup, region mismatches, manual config-file editing, antivirus quarantine, multi-account workflows — is in [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

## For developers

Source, dev environment setup, contributor workflow: [CONTRIBUTING.md](CONTRIBUTING.md).

## More documentation

- [docs/INSTALL-METHODS.md](docs/INSTALL-METHODS.md) — pip install, manual zip extraction, install from source
- [docs/AI-CLIENTS.md](docs/AI-CLIENTS.md) — manual JSON/TOML wiring for Claude Desktop, Claude Code, and Codex (Windows, macOS, Linux)
- [docs/CLI.md](docs/CLI.md) — full `plaud-tools` CLI reference
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — ffmpeg, region mismatches, antivirus quarantine, multi-account
- [CHANGELOG.md](CHANGELOG.md) — release notes
- [SECURITY.md](SECURITY.md) — security policy
- [LICENSE](LICENSE) — LGPL-3.0-or-later

## Important

**Alpha** — APIs and flags may change between minor versions. Pin versions in production wiring and check the [CHANGELOG](CHANGELOG.md) before upgrading.

**Unofficial** — not affiliated with, endorsed by, or sponsored by Plaud Inc. PlaudTools uses Plaud's web API directly, which their Terms of Service may restrict; your account could be rate-limited or suspended. Use at your own risk. You still need a real Plaud account; PlaudTools does not replace the Plaud mobile or web apps.

---

[![CI](https://github.com/massive-value/plaud-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/massive-value/plaud-tools/actions/workflows/ci.yml)
[![Bundle smoke](https://github.com/massive-value/plaud-tools/actions/workflows/ci.yml/badge.svg?event=push&label=bundle-smoke)](https://github.com/massive-value/plaud-tools/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/plaud-tools)](https://pypi.org/project/plaud-tools/)
![status: alpha](https://img.shields.io/badge/status-alpha-orange)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
[![License: LGPL-3.0-or-later](https://img.shields.io/badge/license-LGPL--3.0--or--later-blue)](LICENSE)
