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.