🪟 Windows-MCP

Windows-MCP 是一个轻量级的开源项目，能够实现 AI 代理与 Windows 操作系统之间的无缝集成。作为 MCP 服务器，它弥合了大型语言模型与 Windows 操作系统之间的鸿沟，使代理能够执行诸如 文件导航、应用程序控制、UI 交互、QA 测试 等任务。

mcp-name: io.github.CursorTouch/Windows-MCP

更新

• 为 Windows-MCP 添加了虚拟机支持。更多详情请访问 (windowsmcp.io)[https://windowsmcp.io/]。
• Windows-MCP 在 Claude Desktop 扩展 中用户数已突破 200万。
• 试试使用 Windows-MCP 构建的代理 🪟Windows-Use。
• Windows-MCP 现已在 PyPI 上发布（因此支持 uvx windows-mcp）。
• Windows-MCP 已被添加到 MCP 注册表。

支持的操作系统

• Windows 7
• Windows 8、8.1
• Windows 10
• Windows 11

🎥 演示

https://github.com/user-attachments/assets/d0e7ed1d-6189-4de6-838a-5ef8e1cad54e

https://github.com/user-attachments/assets/d2b372dc-8d00-4d71-9677-4c64f5987485

✨ 核心特性

• 无缝 Windows 集成
  可原生与 Windows UI 元素交互，打开应用、控制窗口、模拟用户输入等。

• 兼容任意 LLM（可选视觉功能） 与许多自动化工具不同，Windows-MCP 不依赖传统的计算机视觉技术或特定的微调模型；它可与任何 LLM 配合使用，从而降低复杂性和设置时间。

• 丰富的 UI 自动化工具集
  包括用于基本键盘、鼠标操作以及捕获窗口/UI 状态的工具。

• 轻量级且开源
  依赖项极少，安装简单，源代码完全开放，采用 MIT 许可证。

• 可定制且可扩展
  轻松调整或扩展工具，以满足您独特的自动化或 AI 集成需求。

• 实时交互
  操作之间的典型延迟（例如从一次鼠标点击到下一次）通常在 0.2 至 0.9 秒 之间，具体数值会因当前运行的应用程序数量、系统负载以及 LLM 的推理速度而略有变化。

• 浏览器自动化 DOM 模式
  State-Tool 提供特殊的 use_dom=True 模式，专门针对网页内容，过滤掉浏览器 UI 元素，从而实现更简洁高效的网页自动化。

🛠️ 安装

注意： 首次安装此 MCP 服务器时，可能需要一两分钟来安装 pyproject.toml 中的依赖项。首次运行时，服务器可能会超时，请忽略并重新启动。

前置条件

• Python 3.13+
• Astra 提供的包管理器 UV，可通过 pip install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh 安装。
• Windows 系统中将默认语言设置为 English；否则，在使用其他语言的 Windows MCP 服务器上，请禁用 App-Tool 功能。

npm install -g @anthropic-ai/mcpb

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ]
    }
  }
}

git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<windows-mcp 目录路径>",
        "run",
        "windows-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\Users\\<user>\\AppData\\Local\\Packages\\Claude_pzs8sxrjxfjjc\\LocalCache\\Roaming\\Claude\\Claude Extensions\\ant.dir.cursortouch.windows-mcp",
        "run",
        "windows-mcp"
      ]
    }
  }
}

git clone https://github.com/CursorTouch/Windows-MCP.git

cd Windows-MCP

{
  "command": "uvx",
  "args": [
    "windows-mcp"
  ]
}

{
  "command": "uv",
  "args": [
    "--directory",
    "<windows-mcp 目录路径>",
    "run",
    "windows-mcp"
  ]
}

npm install -g @google/gemini-cli

{
  "theme": "Default",
  ...
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ]
    }
  }
}

npm install -g @qwen-code/qwen-code@latest

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ]
    }
  }
}

npm install -g @openai/codex

[mcp_servers.windows-mcp]
command="uvx"
args=[
  "windows-mcp"
]

npm install -g @anthropic-ai/claude-code

claude mcp add --transport stdio windows-mcp -- uvx windows-mcp

git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP

claude mcp add --transport stdio windows-mcp -- uv --directory "<路径>" run windows-mcp

claude mcp add --transport stdio windows-mcp -- C:\Users\<user>\.local\bin\uvx.exe windows-mcp

🖥️ 模式

Windows-MCP 支持两种运行模式：本地（默认）和 远程。

本地模式（默认）

在本地模式下，Windows-MCP 直接在您的 Windows 设备上运行，并将其工具暴露给连接的 MCP 客户端。这是个人使用的标准配置。

# 使用 stdio 传输（默认）
uvx windows-mcp

# 或者使用 SSE/可流式 HTTP 进行网络访问
uvx windows-mcp --transport sse --host localhost --port 8000
uvx windows-mcp --transport streamable-http --host localhost --port 8000

您可以设置可选的环境变量来自定义行为——请参阅下方的 环境变量。

远程模式

在远程模式下，Windows-MCP 充当一个 代理，连接到 windowsmcp.io，从而实现云端托管的 Windows 自动化。此模式适用于 MCP 客户端位于远程并通过仪表板连接的情况，仪表板会将请求路由到运行 Windows-MCP 的 Windows 虚拟机。

作为桌面扩展安装时，远程模式应保持在轻量级代理路径上，且在启动前无需构建本地 Windows 自动化依赖项。

必需的环境变量：

示例配置：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ],
      "env": {
        "MODE": "remote",
        "SANDBOX_ID": "your-sandbox-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}

传输选项

⚙️ 环境变量

除非另有说明，所有变量均为可选。您可以通过 claude_desktop_config.json（或您的 MCP 客户端等效配置文件）中的 env 键进行设置。

截图与快照

遥测

调试

远程模式

包含所有本地模式选项的 claude_desktop_config.json 示例：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ],
      "env": {
        "WINDOWS_MCP_SCREENSHOT_SCALE": "0.5",
        "WINDOWS_MCP_SCREENSHOT_BACKEND": "auto",
        "WINDOWS_MCP_PROFILE_SNAPSHOT": "false",
        "ANONYMIZED_TELEMETRY": "true",
        "WINDOWS_MCP_DEBUG": "false"
      }
    }
  }
}

🔨 MCP 工具

MCP 客户端可以使用以下工具与 Windows 交互：

• Click: 在指定坐标处单击屏幕。
• Type: 在元素上输入文本（可选择性地清除现有文本）。
• Scroll: 在窗口或特定区域中垂直或水平滚动。
• Move: 将鼠标指针移动到指定坐标，或拖动（设置 drag=True）。
• Shortcut: 按下键盘快捷键（如 Ctrl+c、Alt+Tab 等）。
• Wait: 暂停指定时长。
• Screenshot: 快速截取桌面并显示光标位置、当前活动/打开的窗口以及图像。为提高速度，跳过 UI 树提取，因此在主要需要视觉上下文时应作为首次调用。支持 display=[0] 或 display=[0,1] 以捕获特定屏幕。
• Snapshot: 捕获完整的桌面状态，适用于需要交互式元素 ID、可滚动区域或 use_dom=True 浏览器提取的工作流。支持 use_vision=True 以包含截图，并支持 display=[0] 或 display=[0,1] 以将返回的快照信息限制在特定屏幕上。
• App: 从开始菜单启动应用程序、调整窗口大小或位置，以及在应用程序之间切换。
• Shell: 执行 PowerShell 命令。
• Scrape: 抓取整个网页的信息。
• MultiSelect: 多选多个项目（文件、文件夹、复选框），可选择性按住 Ctrl 键。
• MultiEdit: 在指定坐标处同时向多个输入字段输入文本。
• Clipboard: 读取或设置 Windows 剪贴板内容。
• Process: 列出正在运行的进程，或根据 PID 或名称终止进程。
• Notification: 发送带有标题和消息的 Windows 通知气泡。
• Registry: 读取、写入、删除或列出 Windows 注册表的值和键。

🤝 与我们联系

关注我们以获取最新资讯并加入社区：

• 📢 在 X 关注我们，了解最新动态

• 💬 加入我们的 Discord 社区

星标历史

👥 贡献者

感谢所有为 Windows-MCP 做出贡献的杰出人士！🎉

我们感谢每一份贡献，无论是代码、文档、错误报告还是功能建议。想参与贡献吗？请查看我们的 贡献指南!

🔒 安全

重要提示：Windows-MCP 具有对系统的完全访问权限，并可执行不可逆的操作。请在部署前仔细阅读我们的全面安全指南。

有关详细的安全信息，包括：

• 工具特定的风险评估
• 部署建议
• 漏洞报告流程
• 合规与审计指南

请阅读我们的安全政策。

📊 遥测

Windows-MCP 会收集使用数据，以帮助改进 MCP 服务器。我们不会跟踪任何个人信息、工具参数或输出内容。

如需禁用遥测，请在您的 MCP 客户端配置中将 ANONYMIZED_TELEMETRY 设置为 false：

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ],
      "env": {
        "ANONYMIZED_TELEMETRY": "false"
      }
    }
  }
}

有关所有可配置选项的完整列表，请参阅环境变量部分。

如需详细了解所收集的数据及其处理方式，请参阅我们的安全政策中的遥测与数据隐私章节。

📝 限制

• 由于 MCP 依赖于辅助功能树，因此无法选择段落中的特定文本部分。（⌛ 正在解决中。）
• Type-Tool 旨在用于输入文本，而非在 IDE 中进行编程，因为它会将整个程序一次性输入到文件中。（⌛ 正在解决中。）
• 此 MCP 服务器无法用于玩视频游戏 🎮。

🪪 许可证

本项目采用 MIT 许可证授权——详情请参阅LICENSE文件。

🙏 致谢

Windows-MCP 使用了多个优秀的开源项目来支持其 Windows 自动化功能：

• UIAutomation

• PyAutoGUI

在此向这些库的维护者和贡献者致以衷心的感谢，感谢他们卓越的工作和开源精神。

🤝 贡献

欢迎贡献！请参阅CONTRIBUTING以获取设置说明和开发指南。

由 CursorTouch 用心打造 ❤️

引用

@software{
  author       = {CursorTouch},
  title        = {Windows-MCP：用于将 LLM 代理与 Windows 集成的轻量级开源项目},
  year         = {2024},
  publisher    = {GitHub},
  url={https://github.com/CursorTouch/Windows-MCP}
}

Windows-MCP 快速上手指南

Windows-MCP 是一个轻量级开源项目，作为 MCP 服务器桥接大语言模型（LLM）与 Windows 操作系统。它允许 AI 智能体直接执行文件导航、应用控制、UI 交互、自动化测试等任务，无需依赖复杂的计算机视觉技术。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：Windows 7, 8, 8.1, 10, 或 11。
• Python 版本：Python 3.13 或更高版本。
• 包管理器：UV (由 Astral 开发)。
  • 安装命令 (任选其一)：

    pip install uv
    # 或
    curl -LsSf https://astral.sh/uv/install.sh | sh
    

• 语言设置：建议将 Windows 系统默认语言设置为 English。如果使用其他语言，可能需要在 MCP 配置中禁用 App-Tool 以避免兼容性问题。

注意：首次安装时，由于需要安装 pyproject.toml 中的依赖项，启动可能需要 1-2 分钟。如果首次运行超时，请忽略错误并重新启动服务器。

安装步骤

以下以最常用的 Claude Desktop 和 命令行直接运行 为例介绍安装方法。

方式一：在 Claude Desktop 中集成 (推荐)

1. 安装 Claude Desktop 并确保证已安装全局 MCP 工具：

   npm install -g @anthropic-ai/mcpb
   

2. 配置文件位置：

   • 普通版：%APPDATA%\Claude\claude_desktop_config.json
   • Microsoft Store (MSIX) 版：%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
   • 提示：如果是 MSIX 版本且遇到 spawn ENOENT 错误，请使用 uv.exe 的绝对路径。

3. 编辑配置文件： 打开 claude_desktop_config.json，添加以下配置（推荐使用 PyPI 源）：

   {
     "mcpServers": {
       "windows-mcp": {
         "command": "uvx",
         "args": [
           "windows-mcp"
         ]
       }
     }
   }
   

   保存文件时请确保编码为 UTF-8 without BOM。

4. 重启 Claude Desktop 即可生效。

方式二：其他客户端 (Gemini CLI / Qwen Code / Codex CLI 等)

大多数支持 MCP 的 CLI 工具配置逻辑相似，只需在对应的配置文件中添加服务器定义。

• Gemini CLI: 编辑 %USERPROFILE%/.gemini/settings.json
• Qwen Code: 编辑 %USERPROFILE%/.qwen/settings.json
• Codex CLI: 编辑 %USERPROFILE%/.codex/config.toml

JSON 配置示例 (适用于 Gemini/Qwen):

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ]
    }
  }
}

TOML 配置示例 (适用于 Codex):

[mcp_servers.windows-mcp]
command="uvx"
args=[
  "windows-mcp"
]

方式三：从源码安装 (高级用户)

如果需要修改代码或使用最新开发版：

1. 克隆仓库：

   git clone https://github.com/CursorTouch/Windows-MCP.git
   cd Windows-MCP
   

2. 在客户端配置中将 command 设为 uv，args 设为：

   ["--directory", "<你的本地仓库绝对路径>", "run", "windows-mcp"]
   

基本使用

安装完成后，Windows-MCP 会自动作为后台服务运行，等待 AI 智能体调用。你无需手动运行额外的启动脚本（除非使用远程模式）。

1. 启动验证

在支持的 AI 客户端（如 Claude Desktop）中，通常可以通过输入 /mcp 命令查看服务器状态，确认 windows-mcp 已连接且状态正常。

2. 简单使用示例

在聊天窗口中，你可以直接用自然语言指示 AI 操作 Windows。例如：

• 文件操作：

  "请列出我桌面上所有的 PDF 文件，并将它们移动到一个名为 'Documents' 的新文件夹中。"

• 应用控制：

  "打开记事本，输入 'Hello World'，然后保存文件到桌面，文件名为 test.txt。"

• UI 交互：

  "点击屏幕左下角的开始菜单，搜索 '计算器' 并打开它。"

3. 特殊模式：浏览器自动化 (DOM Mode)

当需要操作浏览器时，可以指定使用 DOM 模式以获得更干净的状态捕获（过滤掉浏览器自身的 UI 元素）：

"使用 use_dom=True 模式访问 google.com，搜索 'AI tools' 并提取前三个结果的标题。"

4. 运行模式说明

• 本地模式 (Local)：默认模式。直接在当前机器运行，控制当前系统的 UI 和文件。
• 远程模式 (Remote)：需设置环境变量 MODE=remote 并提供 SANDBOX_ID 和 API_KEY。此模式用于连接云端 Windows 虚拟机进行自动化，适合无头服务器场景。