@speakagent/mcp

Model Context Protocol (MCP) server for SpeakAgent — turn any MCP-aware AI assistant (Claude Desktop, Cursor, VS Code with Cline/Copilot, Windsurf, …) into a voice/video transcription + meeting-analysis workbench.

Your AI client gains these tools:

| Tool | What it does | |---|---| | transcribe | Plain-text transcript of an audio/video file | | diarize | Same, but with speaker labels ([Speaker 1], [Speaker 2], …) | | protocol | Structured meeting protocol in Markdown — styles: summary, business, interview | | todo | Pull only the action items as a Markdown checklist | | check_operation | Retrieve the result of a long-running operation by id | | whoami | Sanity-check token + show minutes balance |

Works with local file paths (/Users/me/meeting.mp3) and public HTTPS URLs.

Quick start

Option A — from the SpeakAgent cabinet (1–2 clicks, recommended)

1. Sign in at speakagent.pro and open /profile/api.
2. Press Подключить к {your client} — the cabinet will issue an API token and show you:
   • a one-click deep-link (Cursor, VS Code), or
   • a one-line installer command (Claude Desktop), or
   • a pre-filled JSON config to paste (anything else).
3. Restart the client — done.

Option B — manual

1. Get a bearer token at speakagent.pro/profile/api. The token starts with sk_.
2. Pick a setup method below for your client.

Client setup (manual)

All clients use the same entry shape. The env var SPEAKAGENT_TOKEN is what authenticates your calls.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "speakagent": {
      "command": "npx",
      "args": ["-y", "@speakagent/mcp@latest"],
      "env": { "SPEAKAGENT_TOKEN": "sk_..." }
    }
  }
}

Or run:

npx -y @speakagent/mcp install --token=sk_... --client=claude-desktop

Then restart Claude Desktop.

Cursor

Edit ~/.cursor/mcp.json with the same snippet above, or run:

npx -y @speakagent/mcp install --token=sk_... --client=cursor

VS Code (Cline, Copilot Chat)

Edit the user mcp.json:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json
• Linux: ~/.config/Code/User/mcp.json

Or run:

npx -y @speakagent/mcp install --token=sk_... --client=vscode

Any other MCP client

Add the same mcpServers.speakagent entry to whichever config your client uses. The cabinet's «Другой клиент» tab shows the JSON with your token already embedded.

Prompting examples

In any client, once wired up:

Transcribe /Users/me/interview.mp3 in Russian and summarize it as a business protocol.

Pull just the action items from https://my-cdn/meeting.mp4.

Diarize the recording at ./standup.wav and show me who said what about the release schedule.

For long files (40+ min) the first call may time out and return an operation_id. The assistant should then call check_operation with that id a minute or two later to pick up the final text.

Environment variables

| Variable | Required | Default | Notes | |---|---|---|---| | SPEAKAGENT_TOKEN | yes | — | Bearer token from /profile/api | | SPEAKAGENT_API_BASE | no | https://api.speakagent.pro/v1 | Override for dev/stage | | SPEAKAGENT_POLL_BUDGET_SEC | no | 240 | Max seconds a tool blocks before returning operation_id fallback |

Billing

Every operation consumes your SpeakAgent minute balance — same pool as the web cabinet and Telegram bot. Top up at speakagent.pro/profile/payment.

If you run out mid-tool-call, the MCP server returns a clear bilingual (RU + EN) error telling you exactly how many minutes are missing. The LLM will usually relay it faithfully to the user.

Troubleshooting

• "SPEAKAGENT_TOKEN is required" — env var wasn't set. Double-check the env block in your client's MCP config.
• "Invalid or revoked SpeakAgent token" — re-issue the key at /profile/api.
• "Cannot reach SpeakAgent API" — usually a flaky network. Retry in a minute.
• Tool returned operation_id instead of text — it's a long file and we hit the polling budget. Ask the assistant to call check_operation(operation_id=…).
• Want to inspect the protocol stream? Use the official MCP Inspector:

  npx @modelcontextprotocol/inspector npx -y @speakagent/mcp

Development

git clone https://github.com/legolev/speakagent.git
cd speakagent/packages/mcp
npm install
npm run build
npm test

Run the dev server against a local web-api:

export SPEAKAGENT_TOKEN=sk_dev_...
export SPEAKAGENT_API_BASE=http://localhost:9100/api/v1
npm run inspect

License

MIT — see LICENSE.