AI导哈

Windows 11桌面控制协议

一个模块化的MCP服务器，允许兼容OpenAI的本地LLM通过78种工具完全控制Windows 11桌面，支持LM Studio等本地模型集成和零配置解析。

  • by hypercoreiai
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 hypercoreiai/MCP-LMStudio-Windows-11-Controller

使用说明

MCP LMStudio Win11桌面控制器

一个完全模块化的MCP（模型上下文协议）服务器，使任何与OpenAI兼容的LLM都能完全控制Windows 11桌面。专为使用LM Studio等工具进行严格的本地/LAN操作而设计。处理两种发出本机信号的模型 <tool_call> XML标签 和 生成纯文本的模型，不需要任何配置来区分它们。

建筑一瞥

Local LLM (LM Studio)  ──►  MCP Server  ──►  Parser Router  ──►  Tool Registry  ──►  TSD Applier  ──►  Windows APIs
(e.g., Llama/GPT on LAN)     (stdio/http/sse)   (auto-detects        (78 tools          (retries, hooks,
                              with local models   tag vs text)         across 15          timeouts, rate
                                                   hybrid mode)        modules)           limits, elevation)

快速开始

# 1. Install dependencies
npm install

# 2. Build TypeScript → dist/, then start in stdio mode (default)
npm start

# Or start as an HTTP server on port 3000
npm run start:http

# Or start as an SSE server
npm run start:sse

# For active development (no build step — ts-node runs src/ directly)
npm run dev

测试工具

快速测试单个工具：

# List all available tools
node test_tools.js list

# Show tool schema and required arguments
node test_tools.js schema file.read

# Call a tool
node test_tools.js call system.info '{}'
node test_tools.js call file.list '{"path":"C:\\temp"}'

# Interactive mode
node test_tools.js interactive

LM Studio设置（本地LLM集成）

该项目专为严格的本地/LAN操作而设计，LM Studio作为MCP服务器后端。

1.安装LM Studio

  • 下载并安装 LM工作室.
  • 下载兼容的模型（例如GPT-2、Llama或任何与OpenAI兼容的模型）。

2.启动本地服务器

  • 打开LM工作室。
  • 加载您选择的模型。
  • 在上启动本地服务器 http://localhost:11000 （默认端口）。
  • 确保服务器正在运行且可访问。

3.配置环境变量（可选）

代理工具默认为本地操作，但您可以覆盖：

# Set the local LM Studio endpoint (default: http://localhost:11000/v1)
set OPENAI_BASE_URL=http://localhost:11000/v1

# Set the model name (default: local-model)
set AGENT_MODEL=your-local-model-name

# API key is not required for local LM Studio (defaults to dummy)

4.测试代理

在LM Studio运行的情况下，测试自主查询：

node test_tools.js call agent.execute_query '{"query": "List the files in the current directory"}'

这 agent.execute_query 该工具利用您的本地LLM，使用可用的工具集自主规划和执行多步骤任务。

Qwen集成

代理还可以通过OAuth身份验证使用阿里云的Qwen模型。要启用Qwen：

  1. 运行安装脚本：
node setup_qwen.js
  1. 或者手动设置环境变量：
export USE_QWEN=true
export QWEN_MODEL=qwen3  # or other available models
export QWEN_BASE_URL=https://portal.qwen.ai/v1  # optional, uses default if not set
  1. 运行代理查询-它将在首次使用时自动处理OAuth登录：
node test_tools.js call agent.execute_query '{"query": "What is the capital of France?"}'

首次运行时，代理将：

  • 打开浏览器https://chat.qwen.ai/
  • 提示您输入设备代码
  • 完成OAuth身份验证
  • 将令牌安全地存储在 memories/ 目录
  • 令牌过期时自动刷新令牌

可用的Qwen型号包括 qwen3, coder-model，以及 vision-model.

先决条件

  • Node.js 20+
  • Windows 11 （工具模块调用Win32 API和PowerShell cmdlet）
  • PowerShell 5.1+ （随附Windows，无需安装）

对于可选的低延迟输入模拟路径，请安装本机插件：

npm install ffi-napi

如果跳过此步骤， input_handler 自动回退到基于PowerShell的实现。

配置

config/session.json

关键字 类型 默认值 描述
transportMode "stdio" "http" "sse"
port 编号 3000 HTTP/SSE模式的端口。
modelSupportsToolCallTags true false null
elevationPreApproved 布尔值 false 跳过白名单工具的UAC。
elevationWhitelist string[] [] 允许工具名称在没有提示的情况下提升运行。
logLevel 字符串 "info" Pino日志级别：跟踪、调试、信息、警告、错误、致命。

config/tsds/*.json --任务特定定义

每个文件都会在不接触代码的情况下调整一个工具的运行时行为：

{
  "toolName": "file.delete",
  "retryPolicy": {
    "maxRetries": 2,
    "backoff": "exponential",
    "baseDelayMs": 500,
    "retryableErrors": ["ACCESS_DENIED", "FILE_IN_USE"]
  },
  "timeoutMs": 10000,
  "requiresElevation": false,
  "preHook": "backup_target",
  "postHook": "verify_deleted"
}

TSD字段：

字段 描述
retryPolicy 可重试错误的重试次数和时间
timeoutMs 每次尝试都要戴上硬壁时钟帽
requiresElevation 如果 true，进程必须以管理员身份运行
preHook 执行前运行的命名钩子（可以改变参数）
postHook 执行后运行的命名钩子（可以改变结果）
fallbackTool 如果所有重试都失败，请尝试使用其他工具
rateLimits 每秒通话次数上限，带突发津贴
inputValidation 在基础模式之上分层的更严格的JSON模式

路径沙盒

设置 FILE_MANAGER_SANDBOX 将环境变量转换为分号分隔的允许路径前缀列表。任何 file.* 在任何I/O运行之前，针对此列表之外路径的操作都会被拒绝：

set FILE_MANAGER_SANDBOX=C:\Users\MyUser;C:\Projects

工具参考

窗口管理器(window_manager)

工具 说明
window.list 枚举可见窗口
window.focus 将窗口置于前台
window.move 按像素坐标重新定位
window.resize 调整到给定尺寸
window.minimize 最小化
window.maximize 最大化
window.restore 从最小值/最大值恢复
window.close 发送关闭消息
window.snap 捕捉到Windows 11布局插槽

文件管理器(file_manager)

工具 说明
file.read 读取文件（文本或base64）
file.write 创建/覆盖文件
file.copy 复制文件或目录
file.move 移动/重命名
file.delete 删除文件或目录
file.list 列出带有可选glob过滤器的目录
file.search 递归内容搜索（字符串或正则表达式）
file.open 使用默认应用程序打开
file.properties 文件元数据

流程经理(process_manager)

工具 说明
process.list 列出正在运行的进程
process.start 后台启动
process.kill 终止（优美或有力）
process.wait 等待退出
process.run 启动+等待+捕获输出

输入处理程序(input_handler)

工具 说明
input.type 键入文本
input.key 使用可选修改器按键
input.mouse_click 点击坐标
input.mouse_drag 通过插值运动拖动
input.mouse_scroll 滚动至指定位置
input.hotkey 消防键盘快捷键（例如。 Ctrl+C)

剪贴板管理器(clipboard_manager)

工具 说明
clipboard.get 读取剪贴板（文本、图像、文件列表）
clipboard.set 写文本或图像
clipboard.clear 清除剪贴板

显示管理器(display_manager)

工具 说明
display.list 列出监视器
display.screenshot 捕获屏幕（全屏、监视器或区域）
display.set_resolution 更改分辨率
display.set_dpi 设置DPI缩放
display.set_brightness 设置亮度（笔记本电脑）

注册表管理器(registry_manager)

工具 说明
registry.read 读取密钥或值
registry.write 写入值（HKLM需要标高）
registry.delete 删除键或值
registry.list 列出子键和值
registry.export 导出到.reg文件

计划任务(scheduled_tasks)

工具 说明
task.list 列出计划任务
task.create 使用触发器+动作创建
task.delete 按名称删除
task.enable 启用
task.disable 禁用
task.run_now 立即触发

系统信息(system_info)

工具 说明
system.info 操作系统、主机名、正常运行时间
system.cpu 每个核心的CPU使用率
system.memory RAM使用率
system.disk 每个驱动器的磁盘使用率
system.network 适配器+连接
system.battery 电池电量（笔记本电脑）
system.services Windows服务

内置挂钩

钩子 阶段 它的作用
backup_target pre 将目标文件/注册表项复制到 .backups/
screenshot_focus pre 捕获屏幕截图并将其附加为 _screenshot 在args中
verify_deleted post 如果目标仍然存在，则结果失败
verify_exists post 如果目标不存在，则结果失败
log_action pre+post 将JSON行附加到 audit.log
poll_for_window post 等待进程启动后出现新窗口

添加新工具（4个步骤）

  1. 创建 src/tools/my_tool.ts 实施 ToolModule 接口
  2. 定义架构 --LLM看到的OpenAI函数定义
  3. 编写TSD — config/tsds/my_tool.json 具有重试/挂钩/超时策略
  4. 注册 --添加 import './my_tool'; 到 src/tools/index.ts

无需更改核心代码。解析器、注册表和传输会自动获取它。

运输方式

模式 使用时… 命令
stdio MCP客户端将您作为子进程生成（Claude Desktop，VS Code） npm start
http 您需要用于自定义集成的独立API服务器 npm run start:http
sse 结果很大（截图）或您需要流媒体状态更新 npm run start:sse

安全说明

  • 立面是封闭的。 设置的工具 requiresElevation: true 如果进程没有以管理员身份运行，则TSD中的请求将失败，除非会话预先批准了它们。
  • 路径沙盒 防止在配置的目录之外进行文件操作。
  • 速率限制 通过TSD对每个工具强制执行，以防止失控回路。
  • 审核日志记录 通过 log_action 钩子提供了每次调用的完整轨迹。
  • 销毁前的备份。 file.delete 和 registry.write/registry.delete 全部运行 backup_target 在触摸任何东西之前。

项目结构

mcp-win11-desktop/
├── src/
│   ├── core/
│   │   ├── server.ts            # Entry point & boot orchestrator
│   │   ├── types.ts             # All shared TypeScript types
│   │   ├── errors.ts            # Typed error taxonomy
│   │   ├── logger.ts            # Pino singleton + scoped loggers
│   │   ├── registry.ts          # Tool registry (singleton)
│   │   ├── hooks.ts             # Hook registry + built-in hooks
│   │   ├── parser/
│   │   │   ├── router.ts        # Decides embedding vs text parser
│   │   │   ├── embedding_parser.ts  # <tool_call> tag extraction
│   │   │   └── text_parser.ts   # Plain-text strategy stack
│   │   └── tsd/
│   │       ├── loader.ts        # Reads config/tsds/*.json
│   │       └── applier.ts       # Wraps execute() with TSD policies
│   ├── tools/
│   │   ├── index.ts             # Barrel — imports all tool modules
│   │   ├── window_manager.ts
│   │   ├── file_manager.ts
│   │   ├── process_manager.ts
│   │   ├── input_handler.ts
│   │   ├── clipboard_manager.ts
│   │   ├── display_manager.ts
│   │   ├── registry_manager.ts
│   │   ├── scheduled_tasks.ts
│   │   ├── system_info.ts
│   │   ├── internet_tools.ts
│   │   ├── ui_inspector.ts
│   │   ├── memory_manager.ts
│   │   ├── agent_orchestrator.ts
│   │   ├── virtual_desktop_manager.ts
│   │   └── shell_executor.ts
│   └── transports/
│       ├── http.ts              # Express HTTP server
│       ├── sse.ts               # Server-Sent Events
│       └── stdio.ts             # JSON-RPC over stdin/stdout
├── config/
│   ├── session.json             # Session defaults
│   └── tsds/                    # Per-tool TSD configs (15 files)
├── package.json
├── tsconfig.json
└── README.md

相关 MCP