Speak AI MCP Server & CLI

Connect Claude, Cursor, Windsurf, and other AI assistants to your Speak AI workspace.
83 tools, 5 resources, 3 prompts, 28 CLI commands — transcribe, analyze, search, and manage media at scale.

Quick Start

1. Get Your API Key

1. Go to Speak AI API Keys
2. Copy your API Key

2. Choose How to Use It

Setup

Auto-Setup (Recommended)

Detects installed MCP clients and configures them automatically:

npm install -g @speakai/mcp-server
speakai-mcp init

Manual Setup

{
  "mcpServers": {
    "speak-ai": {
      "command": "npx",
      "args": ["-y", "@speakai/mcp-server"],
      "env": {
        "SPEAK_API_KEY": "your-api-key"
      }
    }
  }
}

export SPEAK_API_KEY="your-api-key"
claude mcp add speak-ai -- npx -y @speakai/mcp-server

{
  "mcpServers": {
    "speak-ai": {
      "command": "npx",
      "args": ["-y", "@speakai/mcp-server"],
      "env": {
        "SPEAK_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "speak-ai": {
      "command": "npx",
      "args": ["-y", "@speakai/mcp-server"],
      "env": {
        "SPEAK_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "speak-ai": {
      "command": "npx",
      "args": ["-y", "@speakai/mcp-server"],
      "env": {
        "SPEAK_API_KEY": "your-api-key"
      }
    }
  }
}

SPEAK_API_KEY=your-key npx @speakai/mcp-server

Environment Variables

MCP Tools (83)

MCP Resources (5)

Resources provide direct data access without tool calls. Clients can read these URIs directly.

MCP Prompts (3)

Pre-built workflow prompts that agents can invoke to run multi-step tasks.

analyze-meeting

Upload a recording and get a full analysis — transcript, insights, action items, and key takeaways.

Parameters: url (required), name (optional)

Example: "Use the analyze-meeting prompt with url=https://example.com/standup.mp3"

research-across-media

Search for themes, patterns, or topics across multiple recordings or your entire library.

Parameters: topic (required), folder (optional)

Example: "Use the research-across-media prompt with topic='customer churn reasons'"

meeting-brief

Prepare a brief from recent meetings — pull transcripts, extract decisions, and summarize open items.

Parameters: days (optional, default: 7), folder (optional)

Example: "Use the meeting-brief prompt with days=14 to cover the last two weeks"

CLI (28 Commands)

Install globally and configure once:

npm install -g @speakai/mcp-server
speakai-mcp config set-key

Or run without installing:

npx @speakai/mcp-server config set-key

Configuration

Media Management

AI & Search

Folders & Clips

Workspace

CLI Options

Every command supports:

• --json — output raw JSON (for scripting and piping)
• --help — show command-specific help

CLI Examples

# Upload and wait for processing
speakai-mcp upload https://example.com/interview.mp3 -n "Q1 Interview" --wait

# Upload a local file
speakai-mcp upload ./meeting-recording.mp4

# Get plain-text transcript
speakai-mcp transcript abc123 --plain > meeting.txt

# Export as PDF with speaker names
speakai-mcp export abc123 -f pdf --speakers

# Ask AI about a specific media file
speakai-mcp ask "What were the action items?" -m abc123

# Ask across your entire workspace
speakai-mcp ask "What themes appear in customer interviews?"

# Search all transcripts
speakai-mcp search "pricing concerns" --from 2026-01-01

# Create a text note from stdin
cat notes.txt | speakai-mcp create-text "Meeting Notes"

# Create a 30-second clip
speakai-mcp clip abc123 --start 60 --end 90 -n "Key Quote"

# Schedule a meeting bot
speakai-mcp schedule-meeting "https://zoom.us/j/123456" -t "Weekly Standup"

# List videos as JSON for scripting
speakai-mcp ls --type video --json | jq '.mediaList[].name'

# List media from the last week
speakai-mcp ls --from 2026-03-19 --to 2026-03-26

# Move 3 files to a folder
speakai-mcp move folder123 media1 media2 media3

Workflow Examples

Transcribe and Analyze a Meeting

You: "Upload and transcribe this recording: https://example.com/meeting.mp3"

AI: I'll upload and analyze that for you.
    -> upload_and_analyze(url, name)
    [waits for processing... returns transcript + insights]

    Here's your transcript with 3 speakers identified.
    Key insights: 5 action items, positive sentiment overall.
    Top topics: Q2 roadmap, hiring plan, budget review.

Research Across Your Library

You: "What themes came up across all our customer interviews this month?"

AI: Let me search your media library.
    -> search_media(query: "customer interview", startDate: "2026-03-01")
    -> ask_magic_prompt(mediaIds: [...], prompt: "What are the recurring themes?")

    Across 12 interviews, the top themes were:
    1. Pricing sensitivity (mentioned in 8/12)
    2. Onboarding friction (6/12)
    3. Feature requests for API access (5/12)

Meeting Automation

You: "Join my 2pm Zoom call, then send me a summary with action items"

AI: -> schedule_meeting_event(meetingUrl, scheduledAt: "2026-03-25T14:00:00Z")

    Done. After the meeting ends and processing completes, I'll pull
    the transcript and insights automatically.

    [After the meeting]
    -> get_media_insights(mediaId)
    -> ask_magic_prompt(mediaIds: [...], prompt: "List all action items with owners")

    Here's your meeting summary with 7 action items...

Build a Weekly Brief

You: "Prepare a brief from all meetings in the last week"

AI: -> list_media(from: "2026-03-18", mediaType: "audio")
    -> get_media_insights(mediaId) [for each of 5 meetings]

    Weekly Meeting Brief (Mar 18-25):
    - Engineering Standup: Deployed v2.3, 2 bugs triaged
    - Sales Review: Pipeline at $1.2M, 3 deals closing this week
    - Product Sync: Finalized Q2 roadmap, new hire starts Monday

    Consolidated Action Items: [12 items grouped by owner]

For Agent Developers

Authentication

The MCP server and CLI handle token management automatically. If you're calling the REST API directly, here's the full auth flow:

Step 1 — Get an access token:

curl -X POST https://api.speakai.co/v1/auth/accessToken \
  -H "Content-Type: application/json" \
  -H "x-speakai-key: YOUR_API_KEY"

Response:

{
  "data": {
    "email": "you@example.com",
    "accessToken": "eyJhbG...",
    "refreshToken": "eyJhbG..."
  }
}

Step 2 — Use the token on all subsequent requests:

curl https://api.speakai.co/v1/media \
  -H "x-speakai-key: YOUR_API_KEY" \
  -H "x-access-token: ACCESS_TOKEN_FROM_STEP_1"

Step 3 — Refresh before expiry:

curl -X POST https://api.speakai.co/v1/auth/refreshToken \
  -H "Content-Type: application/json" \
  -H "x-speakai-key: YOUR_API_KEY" \
  -H "x-access-token: CURRENT_ACCESS_TOKEN" \
  -d '{"refreshToken": "REFRESH_TOKEN_FROM_STEP_1"}'

Token Lifetimes:

Auth Rate Limits: 5 requests per 60 seconds on both /v1/auth/accessToken and /v1/auth/refreshToken.

Data Model Notes

• Folder IDs: Folders have both _id (MongoDB ObjectId) and folderId (string). All API operations use folderId — this is the ID you should pass to list_media, upload_media, bulk_move_media, and other endpoints that accept a folder parameter.
• Media IDs: Media items use mediaId (returned in list responses as _id).

Rate Limits

• The MCP client automatically retries on 429 with exponential backoff
• For direct API usage, implement exponential backoff and respect Retry-After headers
• Cache stable data (folder lists, field definitions, supported languages)
• Use export_multiple_media over individual exports for batch operations
• Use upload_and_analyze instead of manual upload + poll + fetch loops
• Use bulk_move_media to move multiple items at once instead of updating one by one
• Use bulk_update_transcript_speakers to rename speakers across many files instead of calling update_transcript_speakers per file
• Use list_media with include: ["transcription"] to fetch media with transcripts inline, avoiding N+1 calls to get_transcript

Error Format

All tool errors follow this structure:

{
  "content": [{ "type": "text", "text": "Error: HTTP 401: {\"message\": \"Invalid API key\"}" }],
  "isError": true
}

Development

git clone https://github.com/speakai/speakai-mcp.git
cd speakai-mcp

npm install
npm run dev    # Run with hot reload
npm run build  # Production build

Resources

• Speak AI — Platform
• API Documentation — Full API reference
• MCP Protocol — Model Context Protocol spec
• npm Package — npm registry
• Support — Email us

License

MIT