# Wisprs MCP Server for Claude, Cursor & AI Agents

Drop the Wisprs MCP server into Claude Desktop, Cursor, or any MCP-compatible AI host. It exposes voice-processing tools your AI agent can call directly — transcribe, search, export, and repurpose without writing a single line of integration code.

## Install

```bash
npm install -g @wisprs/mcp
```

## Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wisprs": {
      "command": "npx",
      "args": ["@wisprs/mcp"],
      "env": {
        "WISPRS_API_KEY": "sk_your_api_key"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see the Wisprs tools available in the tool selector.

## Add to Cursor

Open `Cursor → Settings → MCP` and add the same server config above.

## Available tools

| Tool | What it does | Required scope |
|---|---|---|
| `transcribe_url` | Submit a URL for transcription, get a job ID | media:ingest |
| `get_job_status` | Check job progress and get transcriptionId on completion | transcriptions:read |
| `get_transcript` | Fetch the full transcript text for a completed job | transcriptions:read |
| `export_subtitles` | Download SRT, VTT, JSON, or plain text | exports:read |
| `summarize_transcript` | Generate an AI summary | repurpose:run |
| `generate_chapters` | Produce timestamped chapter markers | repurpose:run |
| `extract_quotes` | Pull the top quotable lines | repurpose:run |
| `repurpose_transcript` | Any repurpose mode (thread, blog, show-notes…) | repurpose:run |
| `search_library` | Semantic search across all your transcripts | library:search |
| `list_webhook_endpoints` | List registered webhook endpoints | webhooks:manage |
| `list_documentation` | List all available Wisprs API documentation pages | (none) |
| `get_documentation` | Fetch a documentation page as markdown | (none) |

## Example Claude prompt

```
Transcribe this YouTube video and give me a Twitter thread based on the key points:
https://youtube.com/watch?v=dQw4w9WgXcQ

> Claude will call:
> 1. transcribe_url({ url: "..." })
> 2. get_job_status({ jobId: 42 }) — polls until completed
> 3. repurpose_transcript({ transcriptionId: 99, mode: "thread" })
```

## Key requirements

- Your API key must have scopes matching the tools you want to expose. The MCP server passes the key through to the API unchanged.
- The server runs locally via `stdio` transport — your key never leaves your machine.
- Jobs run on Wisprs infrastructure as usual — the MCP server is just a thin proxy.

## Run without install (npx)

```bash
WISPRS_API_KEY=sk_your_api_key npx @wisprs/mcp
```

## FAQ

### Which MCP clients are supported?

Any client that implements the MCP spec via `stdio` transport. Tested with Claude Desktop (macOS and Windows) and Cursor. Other compatible clients include Windsurf, Zed, and any MCP-enabled VS Code extension.

### Does the MCP server send my API key anywhere?

No. The server runs locally on your machine via `stdio` — your key is passed directly to the Wisprs API over HTTPS and never leaves your machine through any third party.

### What scopes does my API key need?

The server uses whichever tools you expose, so the key needs scopes matching those tools. For full access: `media:ingest`, `transcriptions:read`, `exports:read`, `repurpose:run`, `library:search`, and `webhooks:manage`. Restrict scopes if you only use a subset.