mcp-windows-app-launcher

# mcp-windows-app-launcher [中文文档](README_zh.md) 🚀 A Model Context Protocol (MCP) tool that enables AI assistants like Claude to instantly find and launch Windows applications by name. ## Project Overview `mcp-windows-app-launcher` is an MCP Server that exposes a single `launch_windows_app` tool. When an AI assistant invokes it, the server searches your Windows system through multiple strategies — registry, Start Menu, PATH, and common install directories — to locate the target application's `.exe` path and launch it immediately. Built with the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), it integrates seamlessly with **Claude Desktop** and **Claude Code** via stdio transport. ## Features - **Multi-strategy app discovery** — searches registry `App Paths`, Start Menu `.lnk` shortcuts, system `PATH`, and `Program Files` directories in priority order - **Smart name aliasing** — maps common names to their real executables (e.g. `vscode` → `code`, `edge` → `msedge`, `terminal` → `wt`) - **Async process launching** — uses `asyncio.create_subprocess_exec` for non-blocking app startup - **Robust error handling** — clear, Chinese-localized error messages for missing apps, permission issues, and system errors - **Zero external dependencies beyond MCP SDK** — all Windows interaction uses stdlib (`winreg`, `subprocess`, `asyncio`, `pathlib`) ## Installation & Setup ### Prerequisites - Windows 10 or later - Python 3.10+ ### 1. Clone the repository ```bash git clone https://github.com/ye1430937615-ai/mcp-windows-app-launcher.git cd mcp-windows-app-launcher ``` ### 2. Create a virtual environment and install dependencies ```bash python -m venv .venv .\.venv\Scripts\python -m pip install -r requirements.txt ``` ### 3. Verify the installation ```bash .\.venv\Scripts\python -c "from app_locator import find_app_path; print(find_app_path('notepad'))" ``` You should see the absolute path to `notepad.exe` printed on your terminal. ## How to Configure Configure your MCP client to launch this server. Choose the section that matches your client. ### Claude Desktop Add the following to your Claude Desktop `mcp.json` configuration file: **Windows path** — `%APPDATA%\Claude\mcp.json` ```json { "mcpServers": { "mcp-windows-app-launcher": { "command": "C:\\Users\\ye1430937615-ai\\path\\to\\mcp-windows-app-launcher\\.venv\\Scripts\\python.exe", "args": [ "C:\\Users\\ye1430937615-ai\\path\\to\\mcp-windows-app-launcher\\server.py" ] } } } ``` > [!WARNING] > You **MUST** replace all placeholder paths above with the actual absolute paths on your machine. > - All backslashes in the JSON must be escaped as double backslashes (`\\`). > - The Python executable **must** be the one inside `.venv\Scripts\python.exe`, not the system Python. > > **Tip:** Run the included helper script to generate the correct JSON for your machine automatically: > ```bash > .\.venv\Scripts\python generate_config.py > ``` ### Claude Code (CLI) Add the following to your Claude Code settings file: **Windows path** — `%USERPROFILE%\.claude\settings.json` ```json { "mcpServers": { "mcp-windows-app-launcher": { "type": "stdio", "command": "C:\\Users\\ye1430937615-ai\\path\\to\\mcp-windows-app-launcher\\.venv\\Scripts\\python.exe", "args": [ "C:\\Users\\ye1430937615-ai\\path\\to\\mcp-windows-app-launcher\\server.py" ] } } } ``` Or use `.claudecode/mcp.json` in your project directory for per-project configuration: ```json { "mcpServers": { "mcp-windows-app-launcher": { "type": "stdio", "command": ".\\.venv\\Scripts\\python.exe", "args": ["server.py"] } } } ``` ### 4. Restart your MCP client Restart Claude Desktop or Claude Code. The `launch_windows_app` tool should now be available. Send a message like: > Please launch Notepad for me The assistant will call the tool with `app_name: "notepad"` and the application will start. ## Usage Examples | Prompt | Tool Call | |--------|-----------| | "Launch Firefox" | `launch_windows_app("firefox")` | | "Open VS Code" | `launch_windows_app("code")` | | "Start Windows Terminal" | `launch_windows_app("terminal")` | | "Open Calculator" | `launch_windows_app("calc")` | | "Launch Task Manager" | `launch_windows_app("taskmgr")` | ## How It Works ``` User prompt → Claude → MCP Tool call → server.py → app_locator.py │ ┌────────────┼────────────┐ ▼ ▼ ▼ Registry Start Menu PATH / Dirs │ │ │ └────────────┼────────────┘ ▼ Found .exe path │ ▼ asyncio.create_subprocess_exec() │ ▼ App launches 🎉 ``` 1. `server.py` receives the `launch_windows_app` tool call from the MCP client 2. `app_locator.find_app_path()` searches in priority order: - **Registry App Paths** (HKLM x64, HKLM x32, HKCU) — the standard Windows app registration - **Start Menu** `.lnk` shortcuts — resolved via PowerShell COM - **System PATH** — via `shutil.which()` - **WindowsApps** — Win10/Win11 App Execution Aliases - **Program Files** directory scan — depth-limited to 3 levels 3. `app_locator.launch_app()` starts the found executable via `asyncio.create_subprocess_exec()` ## License MIT — see [LICENSE](LICENSE) for details.