ParrotScribe MCP Server & Lex Copilot

An MCP (Model Context Protocol) server that enables AI agents to interact with the ParrotScribe transcription service on macOS.

Meet Lex: Your Tactical Meeting Copilot

If you are using Opencode, I recommend that you use the pre-configured agent called Lex. Lex transforms passive transcription into an active research and navigation tool.

• Real-time Context: Ask "What's that?" or "What did they just say?" to get instant explanations.
• Zero-Latency Knowledge: Proactively loads domain-specific skills based on transcript keywords.
• Tactical Summaries: Generates structured meeting notes, identifying key facts and action items.
• Persona-Ready: Tailor Lex to any role (Journalist, Researcher, Engineer) via private directives.

Installing Lex

1. Ensure this MCP server is configured in your environment.
2. Copy agent/lex.md from this repository into your local .opencode/agent/ directory.

What It Does

ParrotScribe captures real-time audio from your microphone and system audio, transcribes it using Whisper, and this MCP server exposes that transcription data to AI agents. This enables workflows like:

• Meeting Monitor: AI monitors a live call and surfaces relevant information
• Action Item Tracker: AI detects commitments and prepares follow-up actions
• Real-time Researcher: AI looks up technical terms mentioned in conversation
• Session Summarizer: AI generates structured summaries after calls

Prerequisites

• macOS with ParrotScribe installed
• Node.js 18 or higher
• The pscribe CLI must be available in your PATH (it will be if ParrotScribe is installed correctly)

Installation

Option 1: NPX (Recommended)

No installation needed. Configure your AI agent to run:

npx @johanthoren/parrotscribe-mcp-server

Option 2: Global Install

npm install -g @johanthoren/parrotscribe-mcp-server

Then run with:

parrotscribe-mcp-server

Option 3: From Source

git clone https://github.com/johanthoren/parrotscribe-mcp.git
cd parrotscribe-mcp
npm install
npm run build
node dist/index.js

Configuration

Opencode

Add to your ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "parrotscribe": {
      "type": "local",
      "command": ["npx", "@johanthoren/parrotscribe-mcp-server"]
    }
  }
}

Claude Code

Add to your project's .mcp.json or global MCP config:

{
  "mcpServers": {
    "parrotscribe": {
      "command": "npx",
      "args": ["@johanthoren/parrotscribe-mcp-server"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json (typically at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "parrotscribe": {
      "command": "npx",
      "args": ["@johanthoren/parrotscribe-mcp-server"]
    }
  }
}

Environment Variables (Optional)

| Variable | Description | Default | |----------|-------------|---------| | PSCRIBE_PATH | Path to the pscribe executable. Only needed if pscribe is not in your PATH (edge case). | pscribe |

Available Tools

| Tool | Description | |------|-------------| | pscribe_start | Start real-time audio transcription | | pscribe_stop | Stop/pause the current transcription | | pscribe_status | Get service status, session ID, duration | | pscribe_tail | Get recent transcript entries with filtering | | pscribe_cat | Display complete sessions with time-based filtering | | pscribe_grep | Search for patterns across transcript sessions | | pscribe_sessions | List past transcription sessions | | pscribe_new | Force start a new session |

pscribe_tail Parameters

| Parameter | Type | Description | |-----------|------|-------------| | n | number | Number of entries to return (default: 10) | | since_line | number | Start from line N (for polling) | | status | string | Filter: all, confirmed, unconfirmed, translated, speech | | session_id | string | Read from a specific session |

pscribe_cat Parameters

| Parameter | Type | Description | |-----------|------|-------------| | session_ids | string[] | Session IDs to display (from pscribe_sessions) | | since | string | Show sessions starting after this ISO8601 timestamp | | until | string | Show sessions starting before this ISO8601 timestamp | | last | number | Show last N sessions | | status | string | Filter: all, confirmed, unconfirmed, speech |

Use pscribe_cat for historical queries like "summarize yesterday's standup" - the AI converts natural language time references to ISO8601.

pscribe_grep Parameters

| Parameter | Type | Description | |-----------|------|-------------| | pattern | string | The pattern to search for (regex supported) - required | | since | string | Only search sessions starting after this ISO8601 timestamp | | until | string | Only search sessions starting before this ISO8601 timestamp | | status | string | Filter: all, confirmed, unconfirmed, speech | | ignore_case | boolean | Case-insensitive search | | count | boolean | Show match count per session instead of matches | | after_context | number | Show N lines after each match (-A) | | before_context | number | Show N lines before each match (-B) | | context | number | Show N lines before and after each match (-C) |

Use pscribe_grep for queries like "did anyone mention deployment last week?" or "find all references to the API".

Output Format: TOON

The server returns transcript data in TOON format, a token-efficient format designed for LLM consumption:

transcript{timestamp,source,status,segment,confidence,duration,language,text}:
  2024-01-15T14:30:00+01:00,M,C,1,0.95,2.5,en,Hello world
  2024-01-15T14:30:05+01:00,S,C,2,0.92,3.1,sv,Hej dar

Fields

| Field | Description | |-------|-------------| | timestamp | ISO8601 with timezone | | source | M (microphone), S (system audio), E (events) | | status | C (confirmed), U (unconfirmed), T (translated), N (no_speech) | | segment | Incrementing segment number | | confidence | Whisper confidence score (0.0-1.0) | | duration | Segment duration in seconds | | language | ISO 639-1 code (e.g., en, sv, de) | | text | Transcribed content |

Polling Strategy

For real-time monitoring, agents should:

1. Call pscribe_status to ensure a session is active
2. Call pscribe_tail with n: 10 to get initial context
3. Note the last_line number from the response metadata
4. Periodically call pscribe_tail with since_line: last_line + 1
5. Use status: "confirmed" to focus on finalized transcriptions

Example Prompts

See the examples/ directory for ready-to-use prompts:

• standup.md: Daily standup meeting assistant
• retro.md: Sprint retrospective facilitator
• code-review.md: Code review meeting tracker
• pair-programming.md: Pair programming session monitor
• adr.md: Architecture Decision Record generator

Security & Privacy

• Local-Only: Data flows exclusively from the local pscribe CLI to the local AI agent via stdio
• Zero-Cloud: No analytics, no telemetry, no intermediate servers
• User Control: You decide when transcription is active and which AI agent receives the data

Development

# Install dependencies
npm install

# Development mode (auto-reload)
npm run dev

# Build
npm run build

# Test with MCP inspector
npm run inspect

License

MIT

Links

• ParrotScribe App
• Model Context Protocol
• TOON Format