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:
claude mcp add windy-word --command "npx" --args "-y" "windy-word-mcp"
Or in ~/.claude.json / ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"windy-word": {
"command": "npx",
"args": ["-y", "windy-word-mcp"]
}
}
}
Local-dev (cloned repo):
git clone https://github.com/sneakyfree/windy-word-mcp && cd windy-word-mcp
npm install
claude mcp add windy-word --command "node" --args "$(pwd)/bin/windy-word-mcp.js"
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) |
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.
| 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 |
| 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
┌──────────────────────────┐
│ Agent (Claude Code etc) │
└──────────┬───────────────┘
│ MCP over stdio
▼
┌─────────────────────────────────────────┐
│ windy-word-mcp (this package) │
│ - 115 zod-validated tool schemas │
│ - Per-tool timeout overrides │
│ - Structured 4xx body pass-through │
│ - "Windy Word not running" detection │
└──────────┬──────────────────────────────┘
│ HTTP localhost:18765
▼
┌─────────────────────────────────────────┐
│ Windy Word (Electron) — windy-pro repo │
│ - 49-entry settings catalog │
│ - 13 Doctor checks │
│ - Paste-strategy registry (12 backends)│
│ - Whisper Python engine (WebSocket) │
│ - Voice clone + archive on-disk state │
└──────────┬──────────────────────────────┘
│ HTTPS (only for cloud-diagnose)
▼
┌─────────────────────────────────────────┐
│ windy-fix-me CF Worker │
│ - SHARED_SECRET auth │
│ - 20 req/IP/min rate limit │
│ - Claude Haiku 4.5 via OpenRouter │
└─────────────────────────────────────────┘
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_platform calls)
- 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:
v0.1.0 20 foundation
v0.2.0 24 install_dependency + polkit auto-approve
v0.3.0 27 settings catalog
v0.4.0 33 async install + Windy Doctor + cross-platform
v0.5.0 34 cloud_diagnose
v0.6.0 35 paste injection + tag filter
v0.7.0 41 voice clones Phase 1
v0.8.0 46 archive surface
v0.9.0 53 translation + documents
v0.10.0 56 utilities + OC5 macOS Doctor merge
v0.11.0 57 transcribe_audio_file
v0.12.0 60 soul-file export + voice-clone Phase 2 starters
v1.0.0 60 stable API surface declared
v1.5.0 95 Waves W1–W6: window/state, archive search, lifecycle, recording verbs, cloud submit
v1.6.0 104 account / billing / plan surface
v1.7.0 107 TTS round-trip
v1.8.0 109 settings undo + audit log
v1.9.0 111 music ducking
v1.10.0 115 bulk clone-ingest
License
MIT. See LICENSE.
Contributing
Bug reports + tool additions welcome. See PUBLISHING.md for the release recipe.