DeskSense

DeskSense 是一个轻量级、只读的 Windows MCP 服务器，让 AI 助手能够感知当前 PC 的状态。

它通过本地服务器暴露 MCP Streamable HTTP，并由 Bearer Token 保护。CORS 可配置，支持基于浏览器的客户端。当节点需要受控的公共访问时，可选择使用 Cloudflare Tunnel。

DeskSense 是什么

在你想要观察的每台 Windows PC 上运行一个独立的 DeskSense 节点。节点读取桌面和系统状态；它不执行命令或修改计算机。

Related MCP server: procmon-mcp

特性

• 仅限 Windows，只读的 PC 感知

• MCP Streamable HTTP 端点位于 /mcp

• Bearer Token 认证

• 可配置的 CORS 来源

• 可选的 Cloudflare Named 或 Quick Tunnel 访问

• 通过任务计划程序实现交互式 AtLogOn 自动启动

• 通过 wscript.exe 实现隐藏的服务器启动

• 本地健康端点位于 /healthz

MCP 工具

服务器正好提供以下七个只读工具：

• pc_get_context

• pc_get_focus

• pc_list_open_apps

• pc_get_idle_status

• pc_get_pc_status

• pc_get_top_processes

• pc_get_recent_focus

架构

AI assistant / MCP client
          |
          | HTTPS + Bearer Token (optional public tunnel)
          v
Cloudflare Tunnel (optional)
          |
          v
127.0.0.1:8765  ->  python -m desksense.server
          |
          +--> Windows APIs, psutil, and local focus history

每台计算机都有自己的令牌、配置、运行时数据和可选的隧道。SullyOS 是一个经过测试的示例客户端，并非必需或独占的客户端。

要求

• Windows 10 或更新版本

• Python 3.11 或更新版本

• 仅在使用隧道时需要 cloudflared

• 兼容的 MCP 客户端

快速开始

在 PowerShell 中从仓库根目录执行：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -m desksense.server

如需完整的节点安装，包括令牌生成、CORS、隧道配置和自动启动任务：

.\scripts\install.ps1 `
  -Hostname desksense.example.com `
  -TunnelName desksense

当浏览器客户端需要额外的来源时，使用 -AllowedOrigin https://example-client.app。安装程序会打印 MCP URL 和令牌文件路径，但不会打印令牌。

Cloudflare Tunnel

Cloudflare 是可选的。使用 Quick Tunnel 进行临时测试：

.\scripts\start-quick-tunnel.ps1

如需稳定的主机名，请认证 cloudflared，创建或选择 Named Tunnel，并在安装后使用 start-named-tunnel.ps1。将隧道指向 http://127.0.0.1:8765，仅暴露预期的 hostname。

连接 MCP 客户端

使用以下配置客户端：

• MCP URL: https://desksense.example.com/mcp（本地使用 http://127.0.0.1:8765/mcp）

• 认证: Bearer <token>

令牌本地存储在 .secrets\API_KEY.txt 中。SullyOS 可作为示例客户端；任何支持 Streamable HTTP 和 bearer 认证的 MCP 客户端都可以连接。

多台 PC / 节点

每台 Windows PC 安装一个 DeskSense 节点。为每个节点分配不同的 hostname、隧道名称和令牌，然后在客户端中分别配置每个 MCP 端点。除非使用文档记录的迁移工作流，否则不要在不同计算机之间复制节点的运行时数据库或凭据。

安全与隐私

DeskSense 是只读的，但其响应可能包含应用程序名称、窗口标题、进程信息和系统指标。请保持 Bearer Token 的私密性，将 AllowedOrigin 限制为受信任的客户端，并将公共访问放在正确配置的隧道背后。令牌不会写入源代码或日志。焦点历史记录本地存储在 data\pc_sense.db 中；日志写入 logs\ 目录下。

自动启动

安装程序会注册一个名为 DeskSense MCP 的交互式 AtLogOn 任务。它启动 wscript.exe，进而运行 run-desksense-hidden.vbs；VBS 脚本调用 python.exe -m desksense.server，且不显示控制台窗口。

.\scripts\install-autostart.ps1
.\scripts\status.ps1
.\scripts\uninstall-autostart.ps1

交互式登录是故意的，因为桌面感知需要用户的 Windows 会话。

故障排除

• 检查本地健康状态：Invoke-WebRequest http://127.0.0.1:8765/healthz

• 检查端口 8765 的监听器和本地健康端点：.\.scripts\status.ps1

• 查看 logs\ 下的文件（切勿分享 .secrets\）

• 直接从仓库运行时确认 PYTHONPATH=src

• 确认客户端发送 Authorization: Bearer <token> 并使用 /mcp

• 对于隧道问题，请验证 cloudflared 登录、hostname 路由，并且确保只有一个节点运行 Named Tunnel

开发

.\.venv\Scripts\python.exe -m pytest -q

源代码位于 src/desksense；测试位于 tests。服务器可以在本地使用 PYTHONPATH=src 运行，如上所示。

许可证

DeskSense 根据 MIT 许可证发布。请参阅 LICENSE。