# @seameet/mcp

The [SeaMeet](https://seameet.ai) MCP server — let AI agents **record, transcribe, and mine your meetings**. One install works whether or not you have the desktop app, in Claude Code, Claude Desktop, Codex, Antigravity, Cursor, OpenCode, GitHub Copilot CLI, Windsurf, and any MCP client.

It picks the richest available backend automatically and exposes the union of both:

- **Desktop mode** — when the SeaMeet desktop app is **running**, agents get the full recorder toolset (start/stop recordings, screenshots, live transcript, AI artifacts, search). No auth; nothing leaves your machine.
- **Cloud mode** — when the app isn't there, agents read your **synced library** (recordings, transcripts, summaries), **upload a local audio/video file to be transcribed**, and manage webhooks over the network. Authorized by logging into the web app — **no key copy/paste**, works on a headless terminal.

`tools/list` returns the superset of whatever's available; call **`seameet_status`** any time to see the current mode(s).

> **Using Claude or ChatGPT in a chat app?** You don't need this package. Add the **hosted SeaMeet connector** — `https://mcp.seameet.ai/mcp` — and sign in with your SeaMeet account. No install, no API key. See [Hosted connector](#hosted-connector-no-install).

## What you can do

**🎙️ Record & capture** *(desktop mode)*
- Start a recording — microphone, screen, or screen + system audio — `seameet_start_recording`
- Stop — `seameet_stop_recording` · pause/resume audio-only — `seameet_pause_recording` / `seameet_resume_recording`
- Check recording status — `seameet_recording_status` · read the **live transcript** mid-recording — `seameet_get_live_transcript`
- Take a screenshot through SeaMeet — `seameet_take_screenshot`

**📚 Work with recordings** *(desktop = local files · cloud = synced library)*
- List recordings & screenshots — `seameet_list_recordings` · browse files in the save directory — `seameet_list_files` · app settings — `seameet_get_settings`
- Read generated **artifacts** (summary, transcript, SRT, chapters, action items, key decisions, screenshot OCR/description) — `seameet_get_artifact`
- **Search** across artifact text — `seameet_search_text`
- Fetch a recording's asset-bundle manifest — `seameet_get_asset_bundle`
- Rename a file — `seameet_rename_file` · save a new artifact — `seameet_save_artifact` · **regenerate a summary** from a template — `seameet_regenerate_summary` · list templates — `seameet_list_templates`

**☁️ Cloud library** *(cloud mode)*
- List recent synced recordings, including files you transcribed on [app.seameet.ai](https://app.seameet.ai/transcribe) — `seameet_list_recent_recordings` · fetch the summary, the speaker-labeled transcript (paged for long recordings) and chapters, plus action items and key decisions where the summary produced them; the transcript also comes as the same **SRT or VTT** file app.seameet.ai downloads — `seameet_get_recording` · one section (summary, action items, decisions, chapters) of up to 10 recordings at once — `seameet_get_recordings`
- **Transcribe a file from this computer** — upload a local audio or video file (mp3, m4a, mp4, mov, wav, flac, ogg, oga, opus, webm, aac, amr, spx; up to 512 MB and 5 hours) and start a speaker-labeled transcription; it returns an `assetId` right away and tells the agent when to poll `seameet_get_recording` — `seameet_transcribe_file` *(runs in this local client, so it works in Claude Code, Codex, Cursor and Claude Desktop, but not from claude.ai on the web; uses your transcription allowance)*
- Get a temporary media **stream/download URL** — `seameet_get_media_url`
- **Search** your recordings and the ones shared with you — `seameet_search_recordings` *(full snippets need Sync Pro)*
- **Meeting Memory** — find people, organizations and topics — `seameet_search_memory` · read a Memory page with the meetings it cites — `seameet_get_memory_page`
- **Catch up** across 2–5 related recordings, oldest first, with citations — `seameet_whats_changed`
- Rename speakers — `seameet_rename_speakers` · regenerate a recording's summary — `seameet_regenerate_recording_summary` · rename a recording — `seameet_rename_recording`
- Move up to 20 recordings to the **Trash** (restorable for 30 days) — `seameet_trash_recordings` · restore them — `seameet_restore_recordings` · list the Trash — `seameet_list_recent_recordings` with `trashed: true` *(deleting forever stays on app.seameet.ai)*
- Check storage usage — `seameet_get_usage` · how to record with the desktop app — `seameet_desktop_recording_help`
- Manage outbound **webhooks** (signed deliveries on `ai.ready` / `recording.synced`; creating one needs Sync Pro) — `seameet_create_webhook` · `seameet_list_webhooks` · `seameet_update_webhook` · `seameet_delete_webhook`

**🔌 Connection** *(any mode)*
- Which modes are connected — `seameet_status` · disconnect cloud / switch accounts — `seameet_logout`

That's **17 desktop tools + 19 cloud tools** (fetched live, so new releases appear automatically), plus 3 tools that run in this client (`seameet_status`, `seameet_logout`, `seameet_transcribe_file`). A tool the current backend can't serve returns a clear, structured error instead of failing silently.

## Hosted connector (no install)

SeaMeet also runs a hosted MCP server at **`https://mcp.seameet.ai/mcp`**. Add it to Claude or ChatGPT as a connector and sign in with your SeaMeet account (OAuth): no Node.js, no `npx`, no API key to copy. Any verified SeaMeet account works, Free included; Sync Pro unlocks full search snippets, full Meeting Memory pages, and webhooks.

**Which one should I use?**

| | Hosted connector | `@seameet/mcp` (this package) |
|---|---|---|
| Install | none, add a URL | `npx -y @seameet/mcp` |
| Works in | Claude (web, desktop, mobile), ChatGPT (web, desktop), Claude Code, any client that speaks remote MCP with OAuth | Claude Code, Claude Desktop, Codex, Cursor, Antigravity, OpenCode, Copilot CLI, any stdio MCP client |
| Your cloud library (recordings, transcripts, search, Memory, webhooks) | ✓ 19 tools | ✓ the same 19, relayed |
| Record, screenshot, live transcript from the desktop app | — | ✓ 17 desktop tools |
| Transcribe a file on this computer | — | ✓ `seameet_transcribe_file` |

In short: chat apps and cloud-only use → the hosted connector. A coding agent on the same machine as the SeaMeet desktop app, or uploading local files → this package.

**Add it:**

- **Claude on the web** — open [claude.ai/new#customize/connectors/yours](https://claude.ai/new#customize/connectors/yours) (or **Settings → Connectors**) → **Add custom connector** → name `SeaMeet`, URL `https://mcp.seameet.ai/mcp` → **Add** → **Connect** → sign in on app.seameet.ai → **Allow**. A connector added on claude.ai also shows up in the Claude desktop and mobile apps.
- **Claude desktop app** — **Settings → Connectors → Add custom connector**, same URL, same sign-in.
- **ChatGPT on the web** — open [chatgpt.com/plugins](https://chatgpt.com/plugins) → add an MCP server with the URL above → **Authenticate** → sign in → **Allow**.
- **ChatGPT desktop app** — **Plugins → MCP** → add a server, transport **Streamable HTTP**, the URL above, token/header fields left empty → **Authenticate** (no restart needed). Your browser opens app.seameet.ai/connect → sign in → **Allow**. The consent page notes that this app finishes signing in on your own computer (a local `127.0.0.1` address); that is expected for desktop apps.
- **Claude Code** — `claude mcp add --transport http seameet https://mcp.seameet.ai/mcp`, then run `/mcp` to sign in. (Should work; not yet verified end to end.)

Claude asks for read access; the ChatGPT desktop app also asks for write. Read-only tools carry `readOnlyHint`, so clients that honor it can tell them apart from the write tools.

**Hosted tools (19):**

| Tool | Access | What it does |
|---|---|---|
| `seameet_list_recent_recordings` | read | Your most recent synced recordings |
| `seameet_get_recording` | read | A recording's summary, transcript (also as SRT or VTT), notes, chapters and more |
| `seameet_get_recordings` | read | One section of up to 10 recordings at once, e.g. this week's action items |
| `seameet_search_recordings` | read | Full-text search over your recordings and the ones shared with you (snippets need Sync Pro) |
| `seameet_search_memory` | read | Find people, organizations and topics in Meeting Memory |
| `seameet_get_memory_page` | read | A Meeting Memory page with the meetings it cites |
| `seameet_whats_changed` | read | Catch up across 2–5 related recordings, oldest first, with citations |
| `seameet_get_media_url` | read | A temporary stream/download link for a recording |
| `seameet_get_usage` | read | Storage used versus your quota |
| `seameet_desktop_recording_help` | read | How to record with the SeaMeet desktop app |
| `seameet_list_webhooks` | read | Your webhooks, their delivery health and signing secret |
| `seameet_rename_speakers` | write | Rename the speakers in a transcript |
| `seameet_regenerate_recording_summary` | write | Regenerate a recording's summary |
| `seameet_rename_recording` | write | Rename a recording |
| `seameet_trash_recordings` | write | Move up to 20 recordings to the Trash (restorable for 30 days) |
| `seameet_restore_recordings` | write | Restore recordings from the Trash |
| `seameet_create_webhook` | write | Create a webhook (Sync Pro) |
| `seameet_update_webhook` | write | Change a webhook |
| `seameet_delete_webhook` | write | Delete a webhook |

**Disconnect:** open [app.seameet.ai/connectors](https://app.seameet.ai/connectors) (profile menu → **Connect with Claude/ChatGPT**), click **Disconnect** next to the app, then remove the connector in the app.

## Install

**Every client runs the same command — `npx -y @seameet/mcp` — only the config format differs.** Full per-tool recipes: **[INSTALL.md](INSTALL.md)** (mirrored at [app.seameet.ai/mcp/install.md](https://app.seameet.ai/mcp/install.md)).

**Let your agent do it** — already inside a coding agent? Paste:

> Install the SeaMeet MCP server — fetch
> `https://raw.githubusercontent.com/seameet-ai/seameet-mcp/main/INSTALL.md`, apply the section for
> whichever tool you're running in, and tell me how to reload.

**Or pick your tool:**

| Tool | Fastest install |
|---|---|
| **Claude Code** | `claude mcp add seameet -- npx -y @seameet/mcp` |
| **Codex CLI / IDE** | `codex mcp add seameet -- npx -y @seameet/mcp` |
| **GitHub Copilot CLI** | `copilot mcp add seameet -- npx -y @seameet/mcp` |
| **Cursor** | [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=seameet&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzZWFtZWV0L21jcCJdfQ==) (one-click) |
| **Claude Desktop** | one-click `.mcpb` bundle — see [below](#claude-desktop-one-click-bundle) |
| **Antigravity** · **OpenCode** · **anything else** | see [INSTALL.md](INSTALL.md) |

The generic block, accepted by most MCP clients:

```json
{
  "mcpServers": {
    "seameet": { "command": "npx", "args": ["-y", "@seameet/mcp"] }
  }
}
```

### Requirements
- **Node.js ≥ 18.**
- For desktop mode: the [SeaMeet desktop app](https://seameet.ai/download/) installed and **running** — `brew install --cask seameet-ai/tap/seameet` (macOS) or `winget install seameet` (Windows). Needs **v3.2.0+**; an older running app reports `app_outdated`.
- Cloud mode is opt-in and needs no app — the first cloud tool call starts a one-time authorization (below).

### Cloud authorization (one-time, no key copy/paste)
Cloud mode never activates unless you provide `SEAMEET_API_KEY` or complete the device flow. On the first cloud tool call with no key, the agent shows a short code + `https://app.seameet.ai/link`; you open it (signed in), click **Authorize**, and a read+write key is minted and cached at `~/.seameet/credentials.json`. Silent thereafter; revoke any time under **API keys** on your account. To disconnect or switch accounts, call `seameet_logout` (or `rm ~/.seameet/credentials.json`).

### Transcribing large files
`seameet_transcribe_file` uploads in 8 MB parts and sends stage notifications (`notifications/progress`: reading the file, checking your allowance, each part starting and finishing, finishing the upload, starting transcription), at most one per second. Hosts that reset their tool timeout on progress keep waiting while parts move, but a stalled transfer sends nothing, and hosts that don't reset on progress may cut off a long upload either way: in Claude Code, raise the tool timeout for big files, e.g. `MCP_TOOL_TIMEOUT=600000 claude` (10 minutes). Transcription itself runs in the cloud after the tool returns, so only the upload counts.

The file is opened once, before anything is sent, and every part is read from that open file. If it is rewritten, grows, or is replaced at its path during the upload, the upload is stopped with `file_changed` rather than sending a mix of old and new bytes. A recording whose header says it is longer than 5 hours is refused before anything is sent.

### Claude Desktop one-click bundle
`manifest.json` is an [MCPB](https://github.com/anthropics/mcpb) bundle manifest, so the server ships as a one-click Claude Desktop extension:

```bash
npm install && npm run build:mcpb   # → dist/seameet.mcpb
```

Install via **Settings → Extensions → Advanced → Install extension…** and pick `dist/seameet.mcpb`. Claude Desktop runs it with its own Node.js — no terminal needed. (The desktop app still needs to be installed + running for desktop mode.)

### Claude Code plugin (adds a `/seameet` skill)
This repo doubles as a [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). The plugin registers the MCP server **and** a `/seameet` skill that teaches the core workflows (record + transcribe, capture a bug report, mine meetings for action items):

```bash
claude plugin marketplace add seameet-ai/seameet-mcp
claude plugin install seameet@seameet
```

## Try it

Just ask in plain language — the agent picks the right tool (and the right backend). A few starters:

> Record my screen for 2 minutes, then give me the transcript.

> What were the action items from my last meeting?

> Take a screenshot and describe what's on it.

> Transcribe ~/Downloads/interview.m4a

<details>
<summary><b>Desktop mode</b> — a full recording session (app running)</summary>

- "What are my SeaMeet settings — where does it save recordings?"
- "List my summary templates."
- "List my local recordings." · "List the files in my SeaMeet save folder."
- "What's my current recording status?"
- "Start recording my microphone." *(or: "record my whole screen")*
- "Check the recording status now."
- "Show me the live transcript so far."
- "Pause the recording." · "Resume it."
- "Take a screenshot."
- "Stop the recording."
- "List my recordings again — the new one should be on top."
- "Give me the summary and transcript of that recording."
- "Regenerate its summary using one of my templates."
- "Search my recordings for the word '<keyword>'."
- "Rename that recording to 'MCP dual-mode test'."
- "Get the full asset bundle for it."
- "Save this text as a note/artifact on that recording: <text>."

</details>

<details>
<summary><b>Cloud mode</b> — your synced library (no app needed)</summary>

- "List my 5 most recent SeaMeet recordings." · "What did I record in the last 7 days?"
- "Give me the summary of the top recording."
- "Now show its action items and key decisions."
- "Pull the full speaker-labeled transcript for it, and its chapters."
- "Get me a download/stream link for that recording's media."
- "Search my meetings for 'pricing'." · "What does Meeting Memory know about Acme?"
- "What changed across my last three standups?"
- "Transcribe ~/Downloads/interview.m4a" *(uploads it, then checks back until the transcript is ready)*
- "How much SeaMeet storage am I using versus my quota?"
- "Create a webhook to `https://webhook.site/<your-id>` that fires when AI results are ready."
- "List my webhooks with their delivery health and signing secret."
- "Update that webhook to also fire on `recording.synced`."
- "Delete that webhook."
- "What's my SeaMeet connection status?"
- "Disconnect my SeaMeet cloud account." *(forgets the cached key; the next cloud call re-authorizes)*

</details>

## How it works

A thin stdio↔HTTP proxy. The SeaMeet desktop app hosts a localhost-only bridge (`127.0.0.1:3741`, fallbacks 3742/3743) authenticated with a per-launch random secret; on startup it writes credentials to `$TMPDIR/seameet-mcp-bridge-<username>.json` (mode 0600), which this server reads and proxies (`tools/list` → `GET /mcp-bridge/tools`, `tools/call` → `POST /mcp-bridge/call-tool`). Nothing leaves your machine in desktop mode. Cloud mode talks to the hosted SeaMeet worker (the same server as the [hosted connector](#hosted-connector-no-install)) over HTTPS with your minted key. Every request to SeaMeet's cloud carries `User-Agent: seameet-mcp/<version>`.

Full tool reference (for LLMs): [seameet.ai/llms.txt](https://seameet.ai/llms.txt) — also served locally at `http://localhost:3741/llms.txt` while the app runs.

### Errors are machine-readable

Tool failures return structured JSON your agent can branch on:

```json
{ "success": false, "error": { "code": "app_not_running", "tool": "seameet_start_recording",
  "message": "The SeaMeet desktop app is not running.",
  "install": { "macos": "brew install --cask seameet-ai/tap/seameet", "windows": "winget install seameet" },
  "hint": "Ask the user to install and launch it, then retry." } }
```

| Code | Meaning |
|---|---|
| `app_not_running` | Desktop app is closed — launch it (payload carries `install` commands + `downloadUrl`) |
| `app_outdated` | App is running but too old — **update** to `requiredVersion` (don't reinstall the same build) |
| `auth_required` | Cloud tool needs authorization — the payload has a `user_code` + the `/link` URL |
| `insufficient_scope` | The API key is read-only — authorize a read+write key |
| `unsupported_type` / `too_large` / `empty_file` | `seameet_transcribe_file` refused the file before uploading anything (a known length over 5 hours is `session_too_long`, also before uploading) |
| `file_changed` | The file changed during the upload; the upload was stopped — call again once the file is finished being written |
| `insufficient_allowance` / `free_exhausted` / `import_cap_reached` / `daily_import_limit` / `queue_full` / `session_too_long` | Not enough transcription allowance or room right now — the `hint` says what to tell the user |
| `not_entitled` | This account can't transcribe files — check the plan at app.seameet.ai |
| `disabled` | Transcription is turned off for this account — contact support |
| `upload_failed` | The upload stopped; `step` says where (`upsert-asset`, `create`, `part <n>`, `complete`) and the partial upload is aborted (the asset entry may remain in your library). `cleanup: "failed"` means the abort itself failed; SeaMeet clears stale partial uploads on its own |
| `upload_unknown` | The upload was sent but its completion wasn't confirmed (network drop at `complete`) — open `webUrl` to check before uploading again |
| `service_unavailable` | SeaMeet is briefly unavailable — retry in a minute. During the upload `step` says where it stopped; once the upload completed, the payload carries `webUrl` to start transcription there |
| `job_start_failed` | The file is in the library (`assetId`, `webUrl`) but transcription could not start — open `webUrl` to start it; don't re-run the tool, which would upload a duplicate |
| `upload_incomplete` | SeaMeet was still finishing the upload after one retry — open `webUrl` in a minute to start transcription |
| `cancelled` | The host cancelled the call before the transcription request was sent; the partial upload is aborted and no transcription starts |
| `outcome_unknown` | The transcription request was sent but no answer came back (cancel, timeout or network drop) — it may have started, so check `asset.transcriptionJob` with `seameet_get_recording` before doing anything else |
| `app_not_ready` | App is starting up — retry in a few seconds |
| `invalid_request` | A required parameter is missing/invalid — re-check the tool schema |
| `path_forbidden` | `filePath` must be inside the SeaMeet save directory |
| `not_found` | File or artifact doesn't exist — discover it with a list/search tool first |
| `timeout` | App didn't respond in time — check status, retry once |
| `unknown_tool` | Includes `did_you_mean` suggestions |

### Configuration (rarely needed)

| Env var | Purpose |
|---|---|
| `SEAMEET_API_KEY` | Cloud API key (`smk_…`) — skips the device authorization flow |
| `SEAMEET_MCP_CREDENTIALS_FILE` | Explicit path to the desktop-bridge credentials file |
| `SEAMEET_BRIDGE_PORT` + `SEAMEET_BRIDGE_SECRET` | Bypass the bridge credentials file entirely |
| `SEAMEET_CLOUD_CREDENTIALS_FILE` | Where the minted cloud key is cached (default `~/.seameet/credentials.json`) |
| `SEAMEET_REMOTE_URL` / `SEAMEET_DEVICE_URL` | Override the cloud endpoints (default: production) |
| `SEAMEET_SUPABASE_URL` / `SEAMEET_SUPABASE_ANON_KEY` / `SEAMEET_STT_PROXY_URL` / `SEAMEET_WEB_URL` | Override the endpoints `seameet_transcribe_file` uploads to and links (default: production) |

## Development

```bash
npm install
npm test             # wrapper tests (fake bridge + fake cloud) and upload tests (mocked fetch + temp files)
npm run build:mcpb   # validate manifest.json + pack the Claude Desktop extension
```

Releasing is automated — see [PUBLISHING.md](PUBLISHING.md).

## Legal

- Terms: https://seameet.ai/en/terms/
- Privacy: https://seameet.ai/en/privacy/

## License

MIT © [SeaMeet.ai](https://seameet.ai)