TypeWhisper MCP
OfficialThe TypeWhisper MCP server enables coding agents to programmatically control a TypeWhisper application for speech transcription and dictionary management.
Check Status (
typewhisper_status): Verify if the TypeWhisper API is reachable and has a model ready.List Models (
typewhisper_list_models): Retrieve available transcription engines and models.Transcribe Files (
typewhisper_transcribe_file): Submit a local audio or video file for transcription or translation, with options to specify task, model, engine, source language or language hints, target language, and whether to apply dictionary corrections.Search History (
typewhisper_search_history): Query recent transcription history with text search and pagination (limit/offset).Manage Dictionary Terms: List (
typewhisper_list_dictionary_terms), upsert (typewhisper_upsert_dictionary_terms), or delete (typewhisper_delete_dictionary_term) recognition terms, with optional CTC minimum similarity scores.Manage Dictionary Corrections: List (
typewhisper_list_dictionary_corrections), upsert (typewhisper_upsert_dictionary_correction), or delete (typewhisper_delete_dictionary_correction) post-transcription correction rules (original → replacement), with optional case sensitivity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TypeWhisper MCP transcribe the file /Users/me/report.wav"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/mcpFor local development from this repo:
npm install
npm run build
node dist/bin.js --helpMCP 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:
TYPEWHISPER_API_BASE_URL,TYPEWHISPER_API_PORT, andTYPEWHISPER_API_TOKENTypeWhisper discovery files:
macOS:
~/Library/Application Support/TypeWhisper/api-discovery.jsonWindows:
%LOCALAPPDATA%\\TypeWhisper-UserData\\api-discovery.jsonWindows legacy fallback:
%LOCALAPPDATA%\\TypeWhisper\\api-discovery.json
The matching legacy
api-portfilehttp://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-hostThen 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-mcpFor 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_statustypewhisper_list_modelstypewhisper_transcribe_filetypewhisper_search_historytypewhisper_list_dictionary_termstypewhisper_upsert_dictionary_termstypewhisper_delete_dictionary_termtypewhisper_list_dictionary_correctionstypewhisper_upsert_dictionary_correctiontypewhisper_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-runLicense
GPL-3.0-only
Available Tools
10 toolstypewhisper_delete_dictionary_correctionDelete TypeWhisper Dictionary CorrectionCDestructiveIdempotent
Delete one post-transcription correction from the TypeWhisper dictionary.
Inputs: original (required).
typewhisper_delete_dictionary_termDelete TypeWhisper Dictionary TermCDestructiveIdempotent
Delete one recognition term from the TypeWhisper dictionary.
Inputs: term (required).
typewhisper_list_dictionary_correctionsList TypeWhisper Dictionary CorrectionsARead-only
List post-transcription corrections configured in the TypeWhisper dictionary.
Inputs: no named parameters.
typewhisper_list_dictionary_termsList TypeWhisper Dictionary TermsBRead-only
List recognition terms configured in the TypeWhisper dictionary.
Inputs: no named parameters.
typewhisper_list_modelsList TypeWhisper ModelsARead-only
List available TypeWhisper transcription engines and models.
Inputs: no named parameters.
typewhisper_search_historySearch TypeWhisper HistoryCRead-only
Search recent TypeWhisper transcription history.
Inputs: limit, query, offset.
typewhisper_statusTypeWhisper StatusARead-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 CorrectionBIdempotent
Add or update one post-transcription correction in the TypeWhisper dictionary.
Inputs: original (required), replacement (required), caseSensitive.
typewhisper_upsert_dictionary_termsUpsert TypeWhisper Dictionary TermsCIdempotent
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
Scored across 10 tools
Each tool targets a distinct resource and action: dictionary corrections vs terms, models, history, status, and transcription. No overlap in purpose.
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.
Ten tools cover the core functionality of transcription and dictionary management without being excessive or insufficient.
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
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Cursor, Claude, and other MCP agents to interact with the HyperWhisper app for voice transcription, model management, and recording search.MIT
- AlicenseAqualityFmaintenanceEnables 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.811 npmMIT
- AlicenseNot gradedqualityBmaintenanceConnects 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.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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