Provides motion detection for AI agents by monitoring screen regions for changes or stillness without returning actual pixel data.
Also known as Solteris-Dev/pir-mcp
- Stars
- 2
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Oct 12, 2026
- License
- MIT
What is pir MCP?
pir provides motion detection for AI agents by monitoring screen regions for changes or stillness without returning actual pixel data. It exposes 10 tools, such as pir_define_region, pir_define_window, pir_pick_window.
Summary generated from the project's README
About pir MCP server
Monitoring screen activity for changes or stillness without exposing sensitive visual data is what pir-mcp enables for AI agents. Instead of returning actual pixels or images, this server provides motion detection by analyzing screen regions through a coarse grid of averaged color cells. This approach allows an agent to act as a watcher that knows when a build output moves or a status bar stops ticking without the privacy risks associated with full screenshots.
Developers can use tools like pir_pick_region to manually select areas or pir_define_window to track specific application windows that follow the user's movements. The server uses configurable commands like grim, maim, or screencapture to perform the underlying captures, ensuring the agent only sees the motion metrics. By utilizing metrics such as rmse for general movement or peak for detecting small changes like a clock digit, agents can intelligently wait for specific visual events using pir_wait_for_change or pir_wait_for_stillness.
What you can do with it
- 1Detecting frozen status barsAn agent can monitor a specific UI element to trigger an alarm if it stops updating.
- 2Waiting for build completionsAn AI can pause its workflow until it detects movement in a terminal or build output area.
- 3Tracking moving application windowsThe agent can maintain focus on a specific window even if the user moves or resizes it.
- 4Detecting small UI updatesA developer can instruct an agent to watch for tiny changes like a blinking cursor or a ticking clock.
Written from the project's README. Every use case is checked against a quote from it.
How to install pir MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall pir MCP in Claude Code
$ claude mcp add pir-mcp -- npx -y pir-mcpInstall pir MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pir-mcp": {
"command": "npx",
"args": [
"-y",
"pir-mcp"
]
}
}
}Install pir MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pir-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pir-mcp"
]
}
}
}Install pir MCP in VS Code CLI
$ code --add-mcp '{"name":"pir-mcp","type":"stdio","command":"npx","args":["-y","pir-mcp"]}'Install pir MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pir-mcp": {
"command": "npx",
"args": [
"-y",
"pir-mcp"
]
}
}
}Install pir MCP in Codex
$ codex mcp add pir-mcp -- npx -y pir-mcpInstall pir MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pir-mcp] command = "npx" args = ["-y", "pir-mcp"]
Install pir MCP in Gemini CLI
$ gemini mcp add -s user pir-mcp npx -- -y pir-mcpInstall pir MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pir-mcp": {
"command": "npx",
"args": [
"-y",
"pir-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pir-mcp 0.1.0 in an isolated container with no network and no keys. It answered and listed 10 tools.
pir MCP tools 10
Read from the server with tools/listpir_define_regionName a rectangle of the screen to watch. Coordinates are in the global layout the capture tool uses (on a multi-monitor wlroots layout an output left of the primary has negative x). Masks are rects inside the region, in region-local pixels, that are ignored: put a clock or spinner there. Redefining a name replaces it and forgets its last sample.
pir_define_windowWatch a window rather than a fixed rectangle: geometry is looked up from the window id before every capture, so the region follows the window when it moves. A resize counts as maximal change. Masks are window-local. The id is whatever your window-geometry command understands (a Hyprland address like 0x5f3a..., an X11 window id).
pir_pick_windowAsk the person at the screen to click the window to watch (visible windows are offered as boxes; Escape cancels). The region then follows that window. Prefer this over pir_define_window when a human is present.
pir_pick_regionAsk the person at the screen to draw the rectangle to watch (a selector such as slurp appears; Escape cancels). Prefer this over pir_define_region whenever a human is present: they choose what is sensed, and you get the geometry back. Blocks until they finish or the selector times out.
pir_pick_maskAsk the person to draw a rectangle inside an existing region that should be ignored (a clock, a spinner, a caret). Forgets the region's last sample, since masked grids are not comparable to unmasked ones.
pir_list_regionsThe regions currently defined, with their geometry and masks.
pir_remove_regionForget a region.
pir_sampleCapture the region once and score it against the previous sample of the same region (null on the first call). Cheap and non-blocking: use it to check the capture command works, to take a baseline before doing something, or to ask 'did anything happen there since I last looked?'.
pir_wait_for_changeBlock until the region looks different from how it looked when this call started, or until timeout_ms. Returns changed=true with the score, or changed=false with the largest score seen. Use it as a doorbell: 'wake me when the build output moves', 'when the dialog closes', 'when the game loads'.
pir_wait_for_stillnessBlock until consecutive samples have stayed below threshold for still_for_ms, or until timeout_ms. A short window means 'the page/animation has settled, safe to act'. A long window on something that should keep changing (a clock, a progress bar, a status bar) means it is frozen: still=true is then the alarm.
Configuration
PIR_CAPTURE_CMDScreenshot command template writing binary PPM to stdout; {x} {y} {w} {h} substituted. Default: grim (wlroots).
PIR_MAX_WAIT_MSCap for blocking calls, ms (default 540000); keep under the host's MCP tool timeout.
PIR_PICK_WINDOW_CMDInteractive window pick printing the window id. Default: Hyprland + slurp.
PIR_SELECT_CMDInteractive rectangle selector printing 'x,y wxh'. Default: slurp. Empty disables the pick tools.
PIR_WINDOW_GEOMETRY_CMDPrints 'x,y wxh' for window {id}. Default: Hyprland via jq. Empty disables window regions.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesolteris-dev/pir-mcp is public and reachablegithub.com/solteris-dev/pir-mcp ↗Pass
- Package names this repository as its sourcepir-mcp names solteris-dev/pir-mcp as sourcenpmjs.com/package/pir-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-12github.com/solteris-dev/pir-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from pir-mcpPass
- No critical advisory in the package or its dependencies4 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpir-mcp
A motion sensor for AI agents.
"Gives your LLM agents enough info to be a helpful "watcher" without being a privacy nightmare like Windows Recall" -Solteris-Dev
A PIR sensor tells you that something moved, never what. This is the same idea for a screen: an MCP server that watches named rectangles and answers "did this change?" and "has this gone still?" with a number, a size and a timestamp. No tool in it returns pixels, image files, or anything that could be turned back into a picture.
It exists because an agent driving a desktop keeps needing the same two things: wake me when the build output moves and tell me if this status bar has stopped ticking. Both are motion questions. Neither needs a screenshot.
What it does
pir_pick_regionask the person at the screen to draw the rectangle, the way a regional screenshot works (slurp, slop). The human chooses what is sensed; the agent gets the geometry. Use this whenever someone is there.pir_pick_maskthe same gesture for a patch inside a region to ignore (a clock, a spinner, a caret).pir_define_regionthe scriptable path: name a rectangle by global layout coordinates, with optional masks.pir_pick_window/pir_define_windowwatch a window instead of a fixed rectangle. Its geometry is looked up again before every capture, so the region follows the window when it moves; a resize counts as maximal change. The pick offers your visible windows as boxes to click.pir_samplecapture once, score against the previous sample of that region. Cheap; also the way to check the capture command works.pir_wait_for_changeblock until the region departs from how it looked when the call began, or time out. A doorbell.pir_wait_for_stillnessblock until nothing has changed forstill_for_ms, or time out. A short window means "the animation settled, safe to act". A long window on something that should keep changing means it is frozen, andstill=trueis the alarm.pir_list_regions,pir_remove_regionhousekeeping.
Every comparison reports two numbers over a coarse grid of averaged colour cells (at most 64 across, each at least 4 px), both 0 for identical and 1 for black against white:
rmseover the whole grid: did the region as a whole move? A cursor edge or an antialiased caret scores about 0.02; a dialog opening 0.1 or more. This is the default metric, threshold 0.05.peakthe single most-changed cell: did anything in it move? A clock digit flipping inside a 1920-wide status bar scores rmse 0.018 (invisible to the default) but peak 0.145. Usemetric=peakfor a small thing that should tick inside a larger region.
Averaging is what makes this a sensor rather than a camera: 64 cells cannot be read.
What it deliberately does not do
- It never returns image data. There is no snapshot tool and none is planned. If an agent needs to see, use the screenshot tool your environment already has, so that choice stays explicit and yours.
- It never writes frames to disk. A capture lives in memory for the milliseconds it takes to reduce it to a grid, and only the grid of the last sample is kept per region.
- It does not capture on its own. Every sample is a tool call the agent made,
visible in the transcript, and
pir_pick_regioncarries apurposeline the agent has to write down before you draw.
What it does reveal, so you can decide whether that is acceptable: that a given rectangle changed, at a given time, by a given magnitude. On a region covering a chat window that is presence information. Choose regions accordingly; the server has no opinion.
The capture itself is delegated to a command you configure, run with your
privileges. The default is grim, so nothing here has screen access that you
did not already give to grim.
Install
It is on npm as pir-mcp and in
the official MCP Registry
as io.github.Solteris-Dev/pir-mcp, so most clients can run it with
npx -y pir-mcp and no clone:
claude mcp add -s user pir -- npx -y pir-mcp
From source:
git clone https://github.com/Solteris-Dev/pir-mcp
cd pir-mcp && npm install && npm run build
Requires Node 20+ and a screenshot tool that can write binary PPM to stdout.
Capture command
PIR_CAPTURE_CMD is a template; {x} {y} {w} {h} are substituted and the
result runs under sh -c. It must print a binary PPM (P6) to stdout.
| environment | command |
|---|---|
| wlroots / Hyprland / Sway (default) | grim -g "{x},{y} {w}x{h}" -t ppm - |
| X11 with maim | maim -g {w}x{h}+{x}+{y} -f png | magick png:- ppm:- |
| X11 with ImageMagick | import -window root -crop {w}x{h}+{x}+{y} +repage ppm:- |
| macOS | screencapture -x -R{x},{y},{w},{h} -t png /dev/stdout | magick png:- ppm:- |
Coordinates are whatever the capture tool uses. On a wlroots layout that is the global layout, so an output placed left of the primary has negative x.
Selector command
PIR_SELECT_CMD runs when an agent calls pir_pick_region or
pir_pick_mask and must print x,y wxh. Set it to an empty string to remove
those tools entirely.
| environment | command |
|---|---|
| wlroots / Hyprland / Sway (default) | slurp -f "%x,%y %wx%h" |
| X11 | slop -f "%x,%y %wx%h" |
| macOS | see contrib/macos (untested) |
Window commands
PIR_WINDOW_GEOMETRY_CMD gets {id} substituted and must print x,y wxh
for that window; PIR_PICK_WINDOW_CMD must print the id of the window the
person chose. Both default to Hyprland (via jq and slurp -r). Set either
to an empty string to remove the corresponding tools. Window ids are limited
to [A-Za-z0-9_.:-] before they reach a shell.
| environment | geometry | pick |
|---|---|---|
| Hyprland (default) | hyprctl -j clients | jq -r --arg id "{id}" '.[] | select(.address==$id) | "\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"' |
visible windows as slurp boxes, prints the address |
| Sway | swaymsg -t get_tree | jq -r '.. | select(.id? == {id}) | "\(.rect.x),\(.rect.y) \(.rect.width)x\(.rect.height)"' |
swaymsg -t get_tree | jq -r '.. | select(.visible? == true) | "\(.rect.x),\(.rect.y) \(.rect.width)x\(.rect.height) \(.id)"' | slurp -r -f '%l' |
| X11 | xdotool getwindowgeometry --shell {id} | awk -F= '/^X/{x=$2}/^Y/{y=$2}/^WIDTH/{w=$2}/^HEIGHT/{h=$2}END{print x","y" "w"x"h}' |
xdotool selectwindow |
Only the Hyprland pair has been run; the others are written from the tools' documentation.
Claude Code
claude mcp add -s user pir -- npx -y pir-mcp
# or, from a source checkout:
claude mcp add -s user pir -- node /path/to/pir-mcp/dist/stdio.js
Blocking calls default to 55 s and are capped by PIR_MAX_WAIT_MS (540 s).
Keep the cap under your host's MCP tool timeout; an agent that needs to watch
for longer just calls again.
Other settings
| variable | default | meaning |
|---|---|---|
PIR_REGIONS |
unset | JSON file of regions to define at startup |
PIR_THRESHOLD |
0.05 |
default change threshold |
PIR_INTERVAL_MS |
500 |
default sampling period |
PIR_DEFAULT_WAIT_MS |
55000 |
default timeout for blocking calls |
PIR_MAX_WAIT_MS |
540000 |
cap for blocking calls |
PIR_CAPTURE_TIMEOUT_MS |
10000 |
how long one capture may take |
PIR_SELECT_TIMEOUT_MS |
60000 |
how long the person has to draw a selection |
PIR_MAX_CELLS |
64 |
grid resolution on the long side; smaller is coarser and more private |
A regions file looks like:
[
{ "name": "bar", "x": 0, "y": 0, "w": 1920, "h": 26,
"masks": [{ "x": 1690, "y": 0, "w": 110, "h": 26 }] }
]
Example
The case that produced this: a status bar that occasionally froze for hours while its process looked healthy. The clock in it should change every minute, so a bar that is still for three minutes is a frozen bar.
pir_pick_region name=bar purpose="watch the status bar for a freeze"
pir_wait_for_stillness name=bar still_for_ms=180000 metric=peak timeout_ms=540000
still=true comes back only if the bar stopped; otherwise the call returns
still=false at the timeout and the agent calls again. Nothing on the screen
was ever seen, and the person drew the rectangle themselves.
Contributing starting points
contrib/macos/ holds an AppKit rectangle selector and capture recipe,
written blind and untested. If you run it on a real Mac, fix what breaks and
send it back.
Tests
npm test
License
MIT.
pir MCP questions
How do I add pir MCP to Claude Code?
Run claude mcp add pir-mcp -- npx -y pir-mcp in your terminal. Add --scope user to make it available in every project.
How do I add pir MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does pir MCP provide?
It exposes 10 tools, including pir_define_region, pir_define_window, pir_pick_window, pir_pick_region, pir_pick_mask.
Does this server return screenshots or image files?
No, it never returns image data or pixels. It only reports numerical scores representing changes in a region to ensure privacy.
How does the motion detection work?
It compares regions using a coarse grid of averaged color cells, providing metrics like RMSE for general movement or peak change for small, specific updates.
Can I watch a specific window instead of a fixed area?
Yes, you can use tools to watch a window, and the geometry is updated before every capture so the monitored region follows the window if it moves.
What tools are required for screen capture?
The server requires a screenshot tool that can write binary PPM to stdout, such as grim, maim, or ImageMagick, depending on your operating system.