mcp-windows-app-launcher

中文文档

🚀 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, 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

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

python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt

3. Verify the installation

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

{
  "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:

.\.venv\Scripts\python generate_config.py

Claude Code (CLI)

Add the following to your Claude Code settings file:

Windows path — %USERPROFILE%\.claude\settings.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:

{
  "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 for details.