Skip to main content
Glama
TypeWhisper MCP

TypeWhisper MCP

Official
by TypeWhisper

TypeWhisper MCP

@typewhisper/mcp exposes the local TypeWhisper API as a Model Context Protocol server for coding agents and other MCP clients.

It connects to a TypeWhisper app running locally or on a remote host and lets agents transcribe files, inspect model status, search transcription history, and manage Dictionary terms and corrections.

Requirements

  • Node.js 20 or newer on the machine running this MCP server

  • TypeWhisper on a reachable macOS or Windows host

  • TypeWhisper local API server enabled under Settings > Advanced

Related MCP server: ParrotScribe MCP Server

Install

npm install -g @typewhisper/mcp

For local development from this repo:

npm install
npm run build
node dist/bin.js --help

MCP Configuration

Most MCP clients can run the server over stdio:

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

For a local checkout:

{
  "mcpServers": {
    "typewhisper": {
      "command": "node",
      "args": ["/Users/marco/Projects/typewhisper-mcp/dist/bin.js"]
    }
  }
}

Discovery

By default, the server mirrors the TypeWhisper CLI discovery behavior:

  1. TYPEWHISPER_API_BASE_URL, TYPEWHISPER_API_PORT, and TYPEWHISPER_API_TOKEN

  2. TypeWhisper discovery files:

    • macOS: ~/Library/Application Support/TypeWhisper/api-discovery.json

    • Windows: %LOCALAPPDATA%\\TypeWhisper-UserData\\api-discovery.json

    • Windows legacy fallback: %LOCALAPPDATA%\\TypeWhisper\\api-discovery.json

  3. The matching legacy api-port file

  4. http://127.0.0.1:8978

Use --dev or TYPEWHISPER_DEV=1 to read development discovery files (TypeWhisper-Dev on macOS and TypeWhisper-DevUserData with a TypeWhisper-Dev fallback on Windows).

typewhisper-mcp --dev
typewhisper-mcp --base-url http://127.0.0.1:8978 --api-token "$TYPEWHISPER_API_TOKEN"

Remote TypeWhisper Host

The MCP server itself can run on any Node.js platform. TypeWhisper currently binds its API to the host's loopback interface, so connect remote clients through a private tunnel instead of exposing the API publicly.

For example, forward a local port from the agent machine to the TypeWhisper host:

ssh -N -L 18978:127.0.0.1:8978 user@typewhisper-host

Then start the MCP server with the forwarded URL and the bearer token from the TypeWhisper host's api-discovery.json:

TYPEWHISPER_API_BASE_URL=http://127.0.0.1:18978 \
TYPEWHISPER_API_TOKEN="your-token" \
typewhisper-mcp

For typewhisper_transcribe_file, the absolute path is resolved by the TypeWhisper host. Remote clients must therefore provide a path that exists on that host, for example through a shared or synchronized directory.

Tools

  • typewhisper_status

  • typewhisper_list_models

  • typewhisper_transcribe_file

  • typewhisper_search_history

  • typewhisper_list_dictionary_terms

  • typewhisper_upsert_dictionary_terms

  • typewhisper_delete_dictionary_term

  • typewhisper_list_dictionary_corrections

  • typewhisper_upsert_dictionary_correction

  • typewhisper_delete_dictionary_correction

typewhisper_transcribe_file requires an absolute path on the TypeWhisper host because TypeWhisper runs as a separate app process.

Recorder and live dictation controls are intentionally not part of the first release.

Development

npm run typecheck
npm test
npm run build
npm pack --dry-run

License

GPL-3.0-only

Available Tools

10 tools
typewhisper_delete_dictionary_correctionDelete TypeWhisper Dictionary CorrectionC
DestructiveIdempotent

Delete one post-transcription correction from the TypeWhisper dictionary.

Inputs: original (required).

typewhisper_delete_dictionary_termDelete TypeWhisper Dictionary TermC
DestructiveIdempotent

Delete one recognition term from the TypeWhisper dictionary.

Inputs: term (required).

typewhisper_list_dictionary_correctionsList TypeWhisper Dictionary CorrectionsA
Read-only

List post-transcription corrections configured in the TypeWhisper dictionary.

Inputs: no named parameters.

typewhisper_list_dictionary_termsList TypeWhisper Dictionary TermsB
Read-only

List recognition terms configured in the TypeWhisper dictionary.

Inputs: no named parameters.

typewhisper_list_modelsList TypeWhisper ModelsA
Read-only

List available TypeWhisper transcription engines and models.

Inputs: no named parameters.

typewhisper_search_historySearch TypeWhisper HistoryC
Read-only

Search recent TypeWhisper transcription history.

Inputs: limit, query, offset.

typewhisper_statusTypeWhisper StatusA
Read-only

Check whether the local TypeWhisper API is reachable and has a model ready.

Inputs: no named parameters.

typewhisper_transcribe_fileTranscribe File with TypeWhisperB

Transcribe a local audio or video file through the running TypeWhisper app.

Inputs: path (required), task, model, engine, +5 more.

typewhisper_upsert_dictionary_correctionUpsert TypeWhisper Dictionary CorrectionB
Idempotent

Add or update one post-transcription correction in the TypeWhisper dictionary.

Inputs: original (required), replacement (required), caseSensitive.

typewhisper_upsert_dictionary_termsUpsert TypeWhisper Dictionary TermsC
Idempotent

Merge or replace TypeWhisper recognition terms.

Inputs: terms, replace, termEntries.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: dictionary corrections vs terms, models, history, status, and transcription. No overlap in purpose.

    Naming Consistency4/5

    All tools follow the 'typewhisper_verb_noun' pattern, but there are minor plural/singular inconsistencies (e.g., 'correction' vs 'corrections', 'term' vs 'terms') that reduce perfect consistency.

    Tool Count5/5

    Ten tools cover the core functionality of transcription and dictionary management without being excessive or insufficient.

    Completeness4/5

    The set provides CRUD operations for dictionary items, plus transcription, model listing, status, and history search. Missing individual get operations for dictionary items, but this is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Enables AI agents to interact with the ParrotScribe transcription service on macOS, providing tools to start/stop transcription, retrieve real-time and historical transcripts, and search across sessions.
      8
      11 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects ChatGPT Web chat directly to a local computer, enabling verified file editing, terminal command execution, Playwright browser automation, code intelligence, and desktop control through the Model Context Protocol. Every operation is backed by pre- and post-condition checks such as SHA-256 byte readback and live DOM validation, so agents can trust that reported successes actually happened.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an editor's AI chat to list and search memos, read action items and open questions, and follow the live recording in progress from the local Wisply app. Connects only to Wisply on the same Mac over a local loopback connection.
      MIT