Back to Browse
Free
Server data from the Official MCP Registry
Control Windy Word voice-to-text from any MCP agent — 60 tools across 12 categories.
About
Control Windy Word voice-to-text from any MCP agent — 60 tools across 12 categories.
Security Report
10.0
Low Risk10.0Low RiskValid MCP server (2 strong, 3 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Host the Windy Word control server is bound to.
Environment variable: WINDY_WORD_MCP_HOST
Control-server port.
Environment variable: WINDY_WORD_MCP_PORT
Per-request timeout to the control server (ms).
Environment variable: WINDY_WORD_MCP_TIMEOUT_MS
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-sneakyfree-windy-word-mcp": {
"env": {
"WINDY_WORD_MCP_HOST": "your-windy-word-mcp-host-here",
"WINDY_WORD_MCP_PORT": "your-windy-word-mcp-port-here",
"WINDY_WORD_MCP_TIMEOUT_MS": "your-windy-word-mcp-timeout-ms-here"
},
"args": [
"-y",
"windy-word-mcp"
],
"command": "npx"
}
}
}Documentation
View on GitHubFrom the project's GitHub 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).
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 | 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
┌──────────────────────────┐
│ 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_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 repos
sneakyfree/windy-pro— the Electron app (Windy Word). Contains the control server, settings catalog, install registry, Doctor checks, paste strategies, archive scanner, voice-clone CRUD.npm install + npm startto run.sneakyfree/windy-fix-me— the cloud-relay Cloudflare Worker. Receives Doctor findings + platform context, returns LLM-augmented remediation via OpenRouter.
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.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Fetch
Freeby Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
80.0K
Stars
4
Installs
5.3
Security
No ratings yet
Local
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
520
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
73
Installs
10.0
Security
4.6
Local