winpc-mcp

从 iPad（Minis）通过 MCP 远程控制 Windows 电脑。

在电脑上运行一个 MCP 服务器，iPad 上的 Minis 通过 HTTP 调用它的工具： 执行命令、管理文件、截屏、控制键盘鼠标、打开应用、管理进程、下载文件等 —— 就像在电脑本地跑了一个 agent。

┌────────── iPad ──────────┐        ┌────────── Windows 电脑 ──────────┐
│ Minis (MCP 客户端)       │  HTTP  │ winpc-mcp (MCP 服务器)          │
│   minis-mcp-cli 调用工具  │◀──────▶│   :8765/mcp  (Bearer Token)     │
└──────────────────────────┘        └──────────────────────────────────┘
          局域网直连 / Tailscale / 隧道

✨ 功能

类别	工具
命令	run_powershell run_cmd run_shell
文件	read_file write_file list_dir search_files delete_file get_file_info
屏幕	screenshot get_screen_size
输入	type_text press_key click move_mouse scroll get_mouse_position get_clipboard set_clipboard
应用	open_app open_url list_windows focus_window close_window
系统	system_info list_process kill_process
网络	http_request download_file serve_file（电脑文件回传给 iPad）

🚀 快速开始

1. 电脑端（Windows）

:: 方式一：一键脚本（自动建虚拟环境、装依赖、启动）
start.bat

:: 方式二：手动
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python server.py

启动后终端会打印：

MCP 地址:    http://192.168.x.x:8765/mcp
Token:       xxxxx（未配置时自动生成，请保存）
Dashboard:   http://192.168.x.x:8765/dashboard

固定 Token：把 config.example.json 复制为 config.json，填入你的 token， 或设置环境变量 WINPC_TOKEN。自动生成的 token 每次重启都会变。

2. iPad 端（Minis）

minis-mcp-cli add --name winpc \
  --url http://<电脑IP>:8765/mcp \
  --header "Authorization: Bearer <token>"

minis-mcp-cli tools winpc        # 查看工具
minis-mcp-cli call winpc system_info   # 测试调用

之后在 Minis 对话里直接说“帮我看看电脑的 CPU 占用”即可。

📊 Dashboard（电脑端实时监控）

电脑浏览器打开 http://<电脑IP>:8765/dashboard（或本机 localhost:8765）：

• DIALOGUE：实时显示 iPad 端对话（Minis 通过 sync_chat 工具同步，或 POST /api/chat）
• TOOL CALLS：每次工具调用的完整记录——参数、结果、耗时、成功/失败状态
• SCREEN + SYSTEM：最近截图画廊（点击放大）+ CPU/内存/磁盘实时状态
• ⌘K 命令面板：过滤工具调用、跳转面板、暂停/恢复实时流、清空日志、复制地址

可配置 dashboard_password 口令保护（开启后首次访问需输入口令）。

🔒 安全

• 所有 /mcp 和 /files 请求必须带 Authorization: Bearer <token>
• 默认只监听局域网；不要把 8765 端口直接映射到公网
• 异地访问推荐 Tailscale（加密隧道），两端装 app 登录同一账号后， MCP 地址直接换成 Tailscale IP（http://100.x.x.x:8765/mcp）即可
• config.json 可配置：
  • allowed_dirs：限定文件操作目录（空 = 不限制，完全操控）
  • confirm_dangerous：true 时删除文件 / 杀进程需显式 confirm=true

⚙️ 配置

{
  "host": "0.0.0.0",          // 监听地址
  "port": 8765,               // 端口
  "token": "",                // MCP 认证 token（留空则自动生成）
  "allowed_dirs": [],         // 文件操作白名单目录（空=不限制）
  "confirm_dangerous": false, // true=危险操作需确认
  "dashboard_password": ""    // Dashboard 访问口令（空=不设防）
}

📝 开发

# 本地（非 Windows）也能启动核心功能测试：
# run_powershell/run_cmd/键盘鼠标/截图等 Windows 专属工具会返回明确错误
pip install -r requirements.txt
python server.py

工具代码在 winpc/ 目录，新增工具 = 在 tools_*.py 里加一个带 @tool 装饰器和 类型注解 + docstring 的函数即可，启动时自动注册。

🛣️ 路线图

• [x] Dashboard：电脑浏览器实时查看对话、工具调用、截图
• [x] Dashboard 动效：状态过渡、计数反馈、清空退出（v1.1.1）
• [ ] 浏览器自动化（CDP 驱动 Chrome）
• [ ] 开机自启（任务计划程序）

📄 License

MIT