Windy Word README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Windy Word listing page.
windy-word-mcp
An MCP (Model Context Protocol) server that turns Windy Word — the voice-to-text desktop app — into an agent-controllable platform. 115 tools spanning paste / hotkeys / transcription / recording verbs / audio devices / install / diagnostics / archive / voice clones / translation / documents / system / window / account + billing / TTS / settings-undo / music-ducking / bulk-clone-ingest / soul-file export.
Windy Word ships a local HTTP control server on 127.0.0.1:18765. This package is a schema-validated MCP wrapper around it. Agents call MCP tools; the server forwards to Windy Word over localhost; everything happens on the user's machine (no network round-trips for state queries).
Install
For most users:
Or in ~/.claude.json / ~/.config/claude/claude_desktop_config.json:
Local-dev (cloned repo):
Requirements
- Node.js ≥ 18
- Windy Word running locally (Electron app — the HTTP control server binds automatically at startup)
Environment overrides
| Variable | Default | Purpose |
|---|---|---|
WINDY_WORD_MCP_HOST | 127.0.0.1 | Override the control-server host |
WINDY_WORD_MCP_PORT | 18765 | Override the control-server port |
WINDY_WORD_MCP_TIMEOUT_MS | 5000 | Default per-request timeout (the install + transcribe tools override this internally for long ops) |
Tool catalog (115 tools, 22 categories)
Regenerate this section's tool count any time with
npm run test:list-tools(node scripts/list-tools.js), which enumerates the live server's registered tools.
Platform (1)
| Tool | What it does |
|---|---|
get_platform | OS, arch, distro, display server, desktop env, xdotool/ydotool presence |
Paste strategies (9)
12 platform-specific paste backends (macOS / Windows / Linux X11 / Linux Wayland) with capability metadata, hotkey-collision auto-detection, and a verified fallback chain.
| Tool | What it does |
|---|---|
list_paste_strategies | All 12 strategies + per-strategy availability + resolved chain + collision flag |
get_active_paste_strategy | Current selection + resolved chain |
set_paste_strategy | Switch active (or "auto") |
test_paste_strategy | Fire a specific strategy at the focused window (injects text!) |
auto_paste | Run the auto-execute chain with explicit candidates |
run_paste_injection_test | Real end-to-end test — spawns Tk target, fires paste, diffs result |
get_paste_history / clear_paste_history | In-memory audit log |
get_paste_target | XWayland vs Wayland-native detection |
Hotkeys (3)
| Tool | What it does |
|---|---|
list_hotkeys | Current bindings + available actions + reserved combos |
set_hotkey | Rebind a global shortcut (Electron accelerator format) |
reset_hotkeys | Restore all global shortcuts to catalog defaults + re-register |
Transcription engine (3)
| Tool | What it does |
|---|---|
list_models | Whisper model catalog + current + WindyTune ladder |
set_model | Switch (hot-reloads Python engine over WebSocket) |
get_windytune_state | Auto-tune state, ladder, recent-timing history |
Recording verbs (8)
| Tool | What it does |
|---|---|
start_recording | Begin a mode-aware recording (batch / streaming / API engine) |
stop_recording | End the recording → trigger transcription + paste pipeline |
cancel_recording | Abort an in-flight recording without saving |
get_recording_state | isRecording + pythonEngineRunning + mode snapshot |
toggle_recording | Start/stop (same effect as the global hotkey) |
paste_transcript | Re-paste the most recent transcript |
set_language | Set the Whisper transcription language (ISO 639-1) |
set_panel_visibility | Configure a bottom panel row (always / hover / off) |
Audio devices (1)
| Tool | What it does |
|---|---|
list_audio_devices | Enumerate microphones available to Windy Word |
install_dependency family (8)
Agent installs missing system tools (Linux/macOS/Windows package managers). Linux uses pkexec; macOS uses user-scope brew; Windows uses winget. Whitelist-only: wtype, ydotool, wl-clipboard, xdotool, cliclick, ffmpeg.
| Tool | What it does |
|---|---|
list_installable_dependencies | What's installable on this machine right now |
install_dependency | Synchronous install (whitelist + dryRun) |
install_dependency_async | Fire-and-poll variant — returns jobId |
get_install_status | Poll a job |
list_install_jobs | All in-memory jobs |
get_install_history / clear_install_history | Audit log |
setup_install_polkit_rule | Install/remove the Linux polkit auto-approve rule |
Polkit setup (Linux): setup_install_polkit_rule installs /etc/polkit-1/rules.d/49-windy-install-deps.rules once per machine to make installs prompt-free. See the rule snippet.
Windy Doctor — local + cloud (3)
13 local rule-based checks covering paste-stack tooling, /dev/uinput permissions, polkit rule presence (with EACCES-tolerant detection), Python engine liveness, Mutter hotkey collision, macOS Accessibility + Microphone permissions, Homebrew presence, cliclick presence.
| Tool | What it does |
|---|---|
run_diagnostics | Run the local battery; return structured findings + actionable remediations |
list_diagnostic_checks | What checks exist + which apply to this platform |
cloud_diagnose | LLM-augment via the windy-fix-me Cloudflare Worker (Claude Haiku 4.5 via OpenRouter) |
Settings catalog (5) — typed/validated agent surface
49 typed catalog entries with tags (archive, voice-clone, transcription, paste, hotkey, ui, geometry, lifecycle, license). Validation runs server-side before any write.
| Tool | What it does |
|---|---|
list_settings | Catalog + current live values + available tags. Supports ?tag=X filter |
describe_setting | Single entry + current value |
set_setting | Validate + apply + return side effects |
get_config | Full electron-store dump (low-level escape hatch) |
set_config | Patch by dotted path, no validation (low-level escape hatch) |
Settings undo (2)
| Tool | What it does |
|---|---|
undo_last_setting_change | Revert the most recent catalog-validated setting change this session |
list_recent_setting_changes | List session setting changes, oldest first |
Archive surface (8) — opaque-id session catalog
Agents work with opaque arc:YYYY-MM-DD:HHMMSS.md ids, never filesystem paths. Path-confined deletes.
| Tool | What it does |
|---|---|
list_archive_entries | List recordings with transcripts + metadata |
get_archive_stats | totalFiles/sizeMB/days/words/sessions (30s server-side cache) |
read_archive_entry | Base64 audio or video for an entry |
delete_archive_entry | Tear down md + audio + video |
open_archive_folder | Pop OS file manager at the archive root |
search_archives | Full-text substring search across every transcript |
archives_by_date_range | Sessions whose start timestamp falls within [from, to] |
bulk_delete_archives | Tear down multiple entries in one call |
Voice clones (10 — Phase 1 + Phase 2)
| Tool | What it does |
|---|---|
list_voice_clones | All clones + activeId (no audio bytes) |
get_active_voice_clone | Currently-active clone (or null) |
set_active_voice_clone | Switch active (or deactivate with null) |
create_voice_clone_from_path | Create from an audio file on disk (path-confined copy) |
delete_voice_clone | Irreversible teardown |
preview_voice_clone | Metadata + optional base64 audio |
list_clone_bundles | Training-bundle catalog |
submit_voice_clone_to_cloud | Submit a local clone to Windy Clone for ElevenLabs training |
get_cloud_clone_order_status | Poll Windy Clone for ElevenLabs training progress |
bulk_ingest_to_clone | Copy a batch of audio files into the voice-samples store as clones |
Bulk clone ingest + watchers (3)
| Tool | What it does |
|---|---|
scan_folder_for_media | Scan a folder (recursive) for audio + video files |
watch_folder_for_recordings | Start/stop a folder watcher that auto-ingests new audio |
list_clone_watchers | List active folder watchers |
Translation (5)
| Tool | What it does |
|---|---|
translate_text | TM-cache-first → Groq/OpenAI fallback (auto-populates cache) |
lookup_translation_memory | Local cache query, no API |
save_translation_memory | Manual upsert |
get_translation_memory_stats | Total / topPairs / recentEntries |
clear_translation_memory | Wipe (destructive) |
Documents (3)
| Tool | What it does |
|---|---|
extract_document_text | Path-based, supports txt/md/csv/html/pdf/docx (5MB default, 20MB cap) |
save_text_file | Path-based write; refuses overwrite unless flagged |
transcribe_audio_file | Any audio file → Whisper transcript via warm WebSocket engine (~5× real-time on CPU) |
Sound effects (7)
| Tool | What it does |
|---|---|
get_sound_effect_state | Per-hook-stage enabled/volume settings (6 lifecycle stages) |
set_sound_hook | Configure a single sound-effect hook stage |
set_active_sound_pack | Switch the active sound pack |
set_master_sfx_volume | Set master SFX volume (0-100) |
set_sound_effect_mode | Switch EffectsEngine mode (silent / classic / surprise / custom / pack) |
list_sound_effect_packs | List known sound-effect packs |
get_widget_state | Mini-widget (tornado) runtime state via the renderer bridge |
System utilities (3) + Forma Animae (1)
| Tool | What it does |
|---|---|
detect_hardware | RAM, CPU, GPU (nvidia-smi + Apple Silicon detect), disk free |
get_autostart_status | Is Windy Word configured to launch on login |
set_autostart | Toggle login-item / .desktop entry |
export_soul_file_to_path | Forma Animae: zip the whole archive (audio + video + transcripts + manifest) for the digital-twin pipeline |
Window + app lifecycle (16)
| Tool | What it does |
|---|---|
get_window_state | Snapshot of maximized/minimized/focused/visible/fullScreen |
minimize_window / maximize_window / unmaximize_window | Title-bar window controls |
bring_window_to_front | Restore + show + raise (does not steal keyboard focus) |
set_window_geometry | Set position + size in screen pixels (live + persisted) |
set_video_fullscreen | Toggle native OS-level fullscreen |
set_always_on_top | Keep the window above others |
set_opacity | Set window opacity (0.1-1.0) |
set_theme | dark / light / auto |
set_font_size | UI zoom factor (70-150%) |
show_hide_window | Cycle main → tornado → hidden → main |
quick_translate | Open the Quick Translate mini-window |
restart_app / quit_app | Relaunch / quit Windy Word (destructive) |
App info + notifications (5)
| Tool | What it does |
|---|---|
get_version | Windy Word + Electron + Node versions |
check_for_updates | Trigger electron-updater's update check |
set_analytics_enabled | Opt in/out of anonymous usage analytics |
open_url | Open an http/https URL or a Windy ecosystem scheme |
send_notification | Show an OS-native notification |
Account + billing (6)
| Tool | What it does |
|---|---|
get_my_plan | Signed-in identity + license tier |
get_billing_history | Purchase / transaction history |
get_billing_summary | Tier + lifetime spend + next renewal |
open_upgrade_checkout | Open Stripe Checkout for an upgrade |
open_billing_portal | Open the Stripe Customer Portal |
logout_account | Sign the user out |
TTS (3)
| Tool | What it does |
|---|---|
speak_text | Speak text aloud through the OS system TTS |
stop_speaking | Silence in-flight TTS playback |
list_tts_voices | List installed system TTS voices |
Music ducking (2)
| Tool | What it does |
|---|---|
pause_other_audio | Pause music/media in other apps (Spotify, Apple Music, browsers, VLC) |
resume_other_audio | Resume what pause_other_audio paused |
Architecture
Coverage
115 MCP tools now surface the Windy Word desktop app's agent-control surface — paste, hotkeys, transcription, recording verbs, audio devices, install/Doctor, archive, voice clones (Phase 1 + Phase 2 cloud training), translation, documents, sound effects, window + app lifecycle, account + billing, TTS, settings-undo, music-ducking, bulk-clone-ingest, and soul-file export. Internal renderer events that are not agent-callable RPCs by design are intentionally excluded.
Quality bar
scripts/stress-test.js exercises every safe tool, including:
- Whitelist rejection at the MCP zod layer
- Structured 4xx error pass-through for validation failures
- Cross-OS rejection (cliclick on Linux, wtype on macOS)
- Real paste injection round-trip (Tk capture + diff)
- Concurrency burst (20 parallel
get_platformcalls) - Idempotent installs (alreadyInstalled detection)
67/67 passing at v1.0.0 release.
Known intermittent: run_paste_injection_test ~1-in-5 hits a Mutter focus-handoff race on Wayland+GNOME. Re-run is clean. Not a regression.
Sibling components
These are private repositories — the names are here so the architecture reads clearly, not as links.
windy-pro— the Electron app (Windy Word). Contains the control server, settings catalog, install registry, Doctor checks, paste strategies, archive scanner, voice-clone CRUD.windy-fix-me— the cloud-relay Cloudflare Worker. Receives Doctor findings + platform context, returns LLM-augmented remediation.
This server is the public, supported interface to Windy Word. You do not need either of the above to use it — install from npm as shown at the top.
Version history
See CHANGELOG.md for the per-version details. Tool count progression:
License
MIT. See LICENSE.
Contributing
Bug reports + tool additions welcome. See PUBLISHING.md for the release recipe.