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