AI导哈

远程桌面控制服务器

一个基于Raspberry Pi OS的远程桌面自动化、文件操作和系统控制服务器，具有分层安全控制。

  • by acredsfan
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 acredsfan/pi-control-mcp

使用说明

Pi控制MCP

Raspberry Pi OS（Debian Trixie）MCP服务器，用于远程桌面自动化、文件操作和系统控制 分级安全控制.

该项目的设计目标是 winremote-mcp，适用于Linux桌面堆栈和Raspberry Pi工作流。

亮点

  • MCP服务器由 FastMCP
  • 目标 Wayland+X11 优雅的回退
  • 实施完整 winremote-mcp 具有Linux/RabRaspberry Pi语义的样式工具界面
  • 分层安全模型：
    • 第1级：只读/低风险
    • 第2层：交互式UI控件
    • 第3层：破坏性/高风险行为
  • 明确的工具包含/排除，实现精细的舒适度控制
  • 支持 标准 和 超文本传输协议 运输设置模式
  • v1安全路线图中包含OAuth支持框架
  • 添加Pi原生附加功能，如 ListWindows, GetActiveWindow, WindowProperties, ListWorkspaces, SwitchWorkspace, ListMonitors, ProbeCapabilities, DetectDialog, WatchClipboard, WatchWindow，以及 GetSessionState

安装

要求：

  • python 3.11+
  • Linux桌面会话（基于Raspberry Pi OS/DDebian的环境）

从此存储库安装：

git clone https://github.com/acredsfan/pi-control-mcp.git
cd pi-control-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

可选附加功能：

# OCR support
python -m pip install .[ocr]

# Backend-specific helpers
python -m pip install .[wayland]
python -m pip install .[x11]

# Development/test tooling
python -m pip install .[test]

快速入门

pi-control-mcp run

默认行为：

  • 启用第1层+第2层
  • 第3级已禁用
  • 除非被覆盖，否则仅本地安全默认值
  • 配置自动加载路径： ./pi-control.toml 然后 ~/.config/pi-control-mcp/pi-control.toml

层级和工具控制

# Enable Tier 3 tools
pi-control-mcp run --enable-tier3

# Disable Tier 2 tools (Tier 1 only)
pi-control-mcp run --disable-tier2

# Include only specific tools
pi-control-mcp run --tools Snapshot,FileList,GetSystemInfo

# Exclude specific tools from resolved set
pi-control-mcp run --exclude-tools Shell,FileWrite

优先： 显式工具>层标志>默认值.

配置

创建 pi-control.toml:

[server]
host = "127.0.0.1"
port = 8090
auth_key = ""
transport = "stdio"

[security]
enable_tier3 = false
disable_tier2 = false
ip_allowlist = ["127.0.0.1/32"]
oauth_client_id = ""
oauth_client_secret = ""

[tools]
enable = []
exclude = []

Raspberry Pi依赖项

对于Trixie上的实际自动化，您可能需要：

  • grim / slurp /Wayland的合成器兼容截图路径
  • ydotool （Wayland投入注入）
  • xdotool 和 xwd/import 对于X11工作流
  • tesseract-ocr 用于OCR
  • wmctrl, xclip / xsel, notify-send, systemctl, journalctl, loginctl, xrandr, wlr-randr, swaymsg

工具类别

桌面和语义UI

  • Snapshot, ObserveScreen, AnnotatedSnapshot
  • OCR, ScreenRecord
  • UIMap, UIMapJson, UIFind, UIClick, UIAct, UISequence, UIWatch
  • Click, Type, Scroll, Move, Shortcut, Wait
  • FocusWindow, MinimizeAll, App

文件、系统和网络

  • FileRead, FileWrite, FileList, FileSearch, FileDownload, FileUpload
  • GetClipboard, SetClipboard, ListProcesses, KillProcess, GetSystemInfo, Notification, LockScreen
  • ServiceList, ServiceStart, ServiceStop, TaskList, TaskCreate, TaskDelete, EventLog
  • RegRead, RegWrite
  • Ping, PortCheck, NetConnections, Scrape

Pi本机会话助手

  • ListWindows, GetActiveWindow, WindowProperties
  • ListWorkspaces, SwitchWorkspace, ListMonitors
  • GetBackendInfo, ProbeCapabilities, GetSessionState
  • DetectDialog, WatchClipboard, WatchWindow
  • ReconnectSession, GetTaskStatus, GetRunningTasks, CancelTask

面向Windows的名称的Linux映射

  • Service* 工具使用 systemctl
  • Task* 这些工具具有Linux友好的语义，可以映射到systemd计时器/cron工作流
  • EventLog 阅读自 journalctl
  • RegRead / RegWrite 通过以下方式映射到桌面设置 gsettings 可用时

安全

看 SECURITY.md 用于部署指导和风险缓解。

Pi内存和割草机诊断

该项目现在包括本地SQLite支持的Pi Memory工具(MemoryRecent, MemorySearch, MemoryNoteAdd等）和安全的无头割草机诊断(ServiceHealthReport, MowerRuntimeSnapshot, HardwareProbe等等）。看 docs/pi-memory.md.

相关 MCP