Windy Word

io.github.sneakyfreePublished by GitHub account sneakyfreev1.3.0Updated Nov 3, 2026

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

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageMedia & Design

Overview

AI-generated overview

MCP wrapper around the Windy Word voice-to-text desktop app, letting an assistant control recording, transcription, paste, archives and settings on the local…

What you can do
  • Start, stop, cancel and toggle recordings, pick Whisper models and language, and re-paste transcripts
  • Control paste strategies and hotkeys, list audio devices, and run paste injection tests
  • Browse, search, read and delete archive entries, and export the whole archive as a soul file
  • Manage voice clones, including cloud training submission, plus folder scanning and watchers
  • Translate text with a local memory cache, extract document text, save files and transcribe audio files
  • Adjust settings with undo, run local diagnostics, control window, theme, TTS, sound effects and music ducking
When to use it
Useful when you already run the Windy Word desktop app and want an assistant to drive dictation, transcription and archive workflows, or to tune the app's paste, hotkey and audio settings without clicking through its UI.
Requirements
Node.js 18 or newer, plus the Windy Word Electron app running locally with its HTTP control server on 127.0.0.1:18765. Optional environment variables WINDY_WORD_MCP_HOST, WINDY_WORD_MCP_PORT and WINDY_WORD_MCP_TIMEOUT_MS override the host, port and timeout. Desktop only.
Before you install
Many tools change state or destroy data: archive and voice-clone deletion is irreversible, restart_app and quit_app close the app, and paste tools inject text into the focused window. install_dependency runs system package managers, and setup_install_polkit_rule installs a prompt-free polkit rule. Billing tools open Stripe checkout and portal, cloud_diagnose sends diagnostics to a third-party worker, and voice-clone submission sends audio for cloud training.

Installation

In SourceWeft

  1. Open Windy Word in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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).

[npm] [mcp registry]

Install

For most users:

bash
claude mcp add windy-word --command "npx" --args "-y" "windy-word-mcp"

Or in ~/.claude.json / ~/.config/claude/claude_desktop_config.json:

json
{  "mcpServers": {    "windy-word": {      "command": "npx",      "args": ["-y", "windy-word-mcp"]    }  }}

Local-dev (cloned repo):

bash
git clone https://github.com/sneakyfree/windy-word-mcp && cd windy-word-mcpnpm installclaude 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

VariableDefaultPurpose
WINDY_WORD_MCP_HOST127.0.0.1Override the control-server host
WINDY_WORD_MCP_PORT18765Override the control-server port
WINDY_WORD_MCP_TIMEOUT_MS5000Default 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)

ToolWhat it does
get_platformOS, 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.

ToolWhat it does
list_paste_strategiesAll 12 strategies + per-strategy availability + resolved chain + collision flag
get_active_paste_strategyCurrent selection + resolved chain
set_paste_strategySwitch active (or "auto")
test_paste_strategyFire a specific strategy at the focused window (injects text!)
auto_pasteRun the auto-execute chain with explicit candidates
run_paste_injection_testReal end-to-end test — spawns Tk target, fires paste, diffs result
get_paste_history / clear_paste_historyIn-memory audit log
get_paste_targetXWayland vs Wayland-native detection

Hotkeys (3)

ToolWhat it does
list_hotkeysCurrent bindings + available actions + reserved combos
set_hotkeyRebind a global shortcut (Electron accelerator format)
reset_hotkeysRestore all global shortcuts to catalog defaults + re-register

Transcription engine (3)

ToolWhat it does
list_modelsWhisper model catalog + current + WindyTune ladder
set_modelSwitch (hot-reloads Python engine over WebSocket)
get_windytune_stateAuto-tune state, ladder, recent-timing history

Recording verbs (8)

ToolWhat it does
start_recordingBegin a mode-aware recording (batch / streaming / API engine)
stop_recordingEnd the recording → trigger transcription + paste pipeline
cancel_recordingAbort an in-flight recording without saving
get_recording_stateisRecording + pythonEngineRunning + mode snapshot
toggle_recordingStart/stop (same effect as the global hotkey)
paste_transcriptRe-paste the most recent transcript
set_languageSet the Whisper transcription language (ISO 639-1)
set_panel_visibilityConfigure a bottom panel row (always / hover / off)

Audio devices (1)

ToolWhat it does
list_audio_devicesEnumerate 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.

ToolWhat it does
list_installable_dependenciesWhat's installable on this machine right now
install_dependencySynchronous install (whitelist + dryRun)
install_dependency_asyncFire-and-poll variant — returns jobId
get_install_statusPoll a job
list_install_jobsAll in-memory jobs
get_install_history / clear_install_historyAudit log
setup_install_polkit_ruleInstall/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.

ToolWhat it does
run_diagnosticsRun the local battery; return structured findings + actionable remediations
list_diagnostic_checksWhat checks exist + which apply to this platform
cloud_diagnoseLLM-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.

ToolWhat it does
list_settingsCatalog + current live values + available tags. Supports ?tag=X filter
describe_settingSingle entry + current value
set_settingValidate + apply + return side effects
get_configThe settings an agent may read, by path (personal values redacted; tokens and consent never returned)
set_configRetired: answers retired, use set_setting

Settings undo (2)

ToolWhat it does
undo_last_setting_changeRevert the most recent catalog-validated setting change this session
list_recent_setting_changesList 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.

ToolWhat it does
list_archive_entriesList recordings with transcripts + metadata
get_archive_statstotalFiles/sizeMB/days/words/sessions (30s server-side cache)
read_archive_entryBase64 audio or video for an entry
delete_archive_entryTear down md + audio + video
open_archive_folderPop OS file manager at the archive root
search_archivesFull-text substring search across every transcript
archives_by_date_rangeSessions whose start timestamp falls within [from, to]
bulk_delete_archivesTear down multiple entries in one call

Voice clones (10 — Phase 1 + Phase 2)

ToolWhat it does
list_voice_clonesAll clones + activeId (no audio bytes)
get_active_voice_cloneCurrently-active clone (or null)
set_active_voice_cloneSwitch active (or deactivate with null)
create_voice_clone_from_pathCreate from an audio file on disk (path-confined copy)
delete_voice_cloneIrreversible teardown
preview_voice_cloneMetadata + optional base64 audio
list_clone_bundlesTraining-bundle catalog
submit_voice_clone_to_cloudSubmit a local clone to Windy Clone for ElevenLabs training
get_cloud_clone_order_statusPoll Windy Clone for ElevenLabs training progress
bulk_ingest_to_cloneCopy a batch of audio files into the voice-samples store as clones

Bulk clone ingest + watchers (3)

ToolWhat it does
scan_folder_for_mediaScan a folder (recursive) for audio + video files
watch_folder_for_recordingsStart/stop a folder watcher that auto-ingests new audio
list_clone_watchersList active folder watchers

Translation (5)

ToolWhat it does
translate_textTM-cache-first → Groq/OpenAI fallback (auto-populates cache)
lookup_translation_memoryLocal cache query, no API
save_translation_memoryManual upsert
get_translation_memory_statsTotal / topPairs / recentEntries
clear_translation_memoryWipe (destructive)

Documents (3)

ToolWhat it does
extract_document_textPath-based, supports txt/md/csv/html/pdf/docx (5MB default, 20MB cap)
save_text_filePath-based write; refuses overwrite unless flagged
transcribe_audio_fileAny audio file → Whisper transcript via warm WebSocket engine (~5× real-time on CPU)

Sound effects (7)

ToolWhat it does
get_sound_effect_statePer-hook-stage enabled/volume settings (6 lifecycle stages)
set_sound_hookConfigure a single sound-effect hook stage
set_active_sound_packSwitch the active sound pack
set_master_sfx_volumeSet master SFX volume (0-100)
set_sound_effect_modeSwitch EffectsEngine mode (silent / classic / surprise / custom / pack)
list_sound_effect_packsList known sound-effect packs
get_widget_stateMini-widget (tornado) runtime state via the renderer bridge

System utilities (3) + Forma Animae (1)

ToolWhat it does
detect_hardwareRAM, CPU, GPU (nvidia-smi + Apple Silicon detect), disk free
get_autostart_statusIs Windy Word configured to launch on login
set_autostartToggle login-item / .desktop entry
export_soul_file_to_pathForma Animae: zip the whole archive (audio + video + transcripts + manifest) for the digital-twin pipeline

Window + app lifecycle (16)

ToolWhat it does
get_window_stateSnapshot of maximized/minimized/focused/visible/fullScreen
minimize_window / maximize_window / unmaximize_windowTitle-bar window controls
bring_window_to_frontRestore + show + raise (does not steal keyboard focus)
set_window_geometrySet position + size in screen pixels (live + persisted)
set_video_fullscreenToggle native OS-level fullscreen
set_always_on_topKeep the window above others
set_opacitySet window opacity (0.1-1.0)
set_themedark / light / auto
set_font_sizeUI zoom factor (70-150%)
show_hide_windowCycle main → tornado → hidden → main
quick_translateOpen the Quick Translate mini-window
restart_app / quit_appRelaunch / quit Windy Word (destructive)

App info + notifications (5)

ToolWhat it does
get_versionWindy Word + Electron + Node versions
check_for_updatesTrigger electron-updater's update check
set_analytics_enabledOpt in/out of anonymous usage analytics
open_urlOpen an http/https URL or a Windy ecosystem scheme
send_notificationShow an OS-native notification

Account + billing (6)

ToolWhat it does
get_my_planSigned-in identity + license tier
get_billing_historyPurchase / transaction history
get_billing_summaryTier + lifetime spend + next renewal
open_upgrade_checkoutOpen Stripe Checkout for an upgrade
open_billing_portalOpen the Stripe Customer Portal
logout_accountSign the user out

TTS (3)

ToolWhat it does
speak_textSpeak text aloud through the OS system TTS
stop_speakingSilence in-flight TTS playback
list_tts_voicesList installed system TTS voices

Music ducking (2)

ToolWhat it does
pause_other_audioPause music/media in other apps (Spotify, Apple Music, browsers, VLC)
resume_other_audioResume 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    foundationv0.2.0  24    install_dependency + polkit auto-approvev0.3.0  27    settings catalogv0.4.0  33    async install + Windy Doctor + cross-platformv0.5.0  34    cloud_diagnosev0.6.0  35    paste injection + tag filterv0.7.0  41    voice clones Phase 1v0.8.0  46    archive surfacev0.9.0  53    translation + documentsv0.10.0 56    utilities + OC5 macOS Doctor mergev0.11.0 57    transcribe_audio_filev0.12.0 60    soul-file export + voice-clone Phase 2 startersv1.0.0  60    stable API surface declaredv1.5.0  95    Waves W1–W6: window/state, archive search, lifecycle, recording verbs, cloud submitv1.6.0  104   account / billing / plan surfacev1.7.0  107   TTS round-tripv1.8.0  109   settings undo + audit logv1.9.0  111   music duckingv1.10.0 115   bulk clone-ingest

License

MIT. See LICENSE.

Contributing

Bug reports + tool additions welcome. See PUBLISHING.md for the release recipe.

Source: README.md at commit 5a33037

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.3.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts