Windy Word

Control Windy Word voice-to-text from any MCP agent — 60 tools across 12 categories.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package windy-word-mcp

Claude Code

claude mcp add windy-word -e 'WINDY_WORD_MCP_HOST=127.0.0.1' -e 'WINDY_WORD_MCP_PORT=18765' -e 'WINDY_WORD_MCP_TIMEOUT_MS=5000' -- npx -y windy-word-mcp@1.3.0

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "windy-word": {
            "command": "npx",
            "args": [
                "-y",
                "windy-word-mcp@1.3.0"
            ],
            "env": {
                "WINDY_WORD_MCP_HOST": "127.0.0.1",
                "WINDY_WORD_MCP_PORT": "18765",
                "WINDY_WORD_MCP_TIMEOUT_MS": "5000"
            }
        }
    }
}

Environment variables

WINDY_WORD_MCP_HOST Host the Windy Word control server is bound to.
WINDY_WORD_MCP_PORT Control-server port.
WINDY_WORD_MCP_TIMEOUT_MS Per-request timeout to the control server (ms).

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

windy-word-mcp
Install
Requirements
Environment overrides
Tool catalog (115 tools, 22 categories)
Architecture
Coverage
Quality bar
Sibling components
Version history
License
Contributing

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)

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`	The settings an agent may read, by path (personal values redacted; tokens and consent never returned)
`set_config`	Retired: answers `retired`, use `set_setting`

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

┌──────────────────────────┐
│  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.

Frequently asked questions

What is Windy Word?

Control Windy Word voice-to-text from any MCP agent — 60 tools across 12 categories.

How do I install Windy Word?

It runs on your machine. In Claude Code: claude mcp add windy-word -e 'WINDY_WORD_MCP_HOST=127.0.0.1' -e 'WINDY_WORD_MCP_PORT=18765' -e 'WINDY_WORD_MCP_TIMEOUT_MS=5000' -- npx -y windy-word-mcp@1.3.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Windy Word need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Windy Word open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Windy Word?

It is published by sneakyfree. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: sneakyfree
Category: Media and design
Runs: Local
GitHub stars: ★ 1
License: MIT
Language: JavaScript
Last commit: Oct 21, 2026
Open issues: 0
Version: 1.3.0
Published: May 20, 2026

io.github.sneakyfree/windy-word-mcp

Similar servers

Eclipse Voiceprint Per-call voice continuity tokens over fixture call records; identifier-level detection ...
Icarus Make any photo or video you can describe, right from Claude.
RooYun AI comic & short-drama studio: scripts to storyboards, image/video generation on an inf...
AISTLabs Video, image and audio generation on top AI models for agents, with an AI director buil...
Lathe Local file and media tools: images, PDFs, audio and video, and OCR. Runs on your machine.
R3 Build 3D web apps: physics, audio, music, Blender import. Live edits, undo, versions, p...
RedNote Trending (小红书): Viral Notes, Full Text & Likes RedNote (Xiaohongshu 小红书) trending notes, no login: full text, images, video, tags, ...
PCBEditor Design, route, check, review and export manufacturable PCBs from plain language; KiCad ...

Media and design

Windy Word

Install

Documentation

windy-word-mcp

Install

Requirements

Environment overrides

Tool catalog (115 tools, 22 categories)

Platform (1)

Paste strategies (9)

Hotkeys (3)

Transcription engine (3)

Recording verbs (8)

Audio devices (1)

install_dependency family (8)

Windy Doctor — local + cloud (3)

Settings catalog (5) — typed/validated agent surface

Settings undo (2)

Archive surface (8) — opaque-id session catalog

Voice clones (10 — Phase 1 + Phase 2)

Bulk clone ingest + watchers (3)

Translation (5)

Documents (3)

Sound effects (7)

System utilities (3) + Forma Animae (1)

Window + app lifecycle (16)

App info + notifications (5)

Account + billing (6)

TTS (3)

Music ducking (2)

Architecture

Coverage

Quality bar

Sibling components

Version history

License

Contributing

Frequently asked questions

`install_dependency` family (8)