TypeWhisper

@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

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