MCP Test Utils

MCP Test Utils

MCP server for automated desktop UI testing. A single binary — no runtime, no dependencies, no installation.

Windows x64 only. macOS and Linux support is planned.

Gives AI agents eyes and hands: screenshots, window management, mouse, keyboard, UI Automation, OCR, file search. Replays saved scenarios as regression runs — after every build, without an agent.

Why

AI agents can trigger actions in applications but can't see the screen. This server bridges that gap:

Agent triggers action → takes screenshot → sees the result →
switches window → clicks a button → verifies → writes report

Fully autonomous, no user involvement required. A path that works can be saved as a scenario and replayed after every build — fast, the same way every time, and without an agent.

Demo

3.26 — Scenario run Claude replays a saved test: 232 steps, one call, 66 s

Installation and setup Setting up the server and the basic tools

Platforms

Tools (26)

Vision

Window Management

Input

Structured UI Access

Waiting, Batching and Scenarios

File Search

Agent Guide

Session Logging

search_in_files and find_files appear only with MCP_SEARCH_DIRS, enable_logging and disable_logging only with MCP_LOG_DIR (see Environment Variables); without them the server lists 22 tools.

Installation

1. Download mcp-test-utils.exe from Releases (the .sig file next to it is for the built-in updater — you do not need it).
2. Add it to your MCP client config. Example below is for Claude Desktop — for other clients, refer to their documentation.

Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe"
    }
  }
}

3. Restart Claude Desktop.
4. In chat, try: "Take a screenshot" — the agent will return an image of your desktop.

With Logging and File Search (optional)

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe",
      "env": {
        "MCP_LOG_DIR": "D:\\path\\to\\logs",
        "MCP_LOG_MAX_MB": "500",
        "MCP_LOG_RETAIN_DAYS": "30",
        "MCP_SEARCH_DIRS": "D:\\Projects\\app1;D:\\Projects\\app2"
      }
    }
  }
}

Quality Presets

Screenshots support configurable quality to balance detail and token cost:

Environment Variables

Tray Log

The server shows a tray icon with a live log of tool calls — one tab per session, errors in red. MCP_NOTIFY=off hides it; the window position is kept in %LOCALAPPDATA%\mcp-test-utils\notify.json.

Updates. The tray menu shows the version and has Check for updates… (once a month the window offers it by itself). Download and install puts a new version from GitHub Releases in place of the running exe — only if it is signed by the author; then restart your MCP client. The server goes online only when you click.

Input Lock

While the server presses keys or clicks, your keyboard and mouse buttons are paused (the mouse still moves) and a notice in the middle of the screen says so. Press Esc to stop it at once. MCP_INPUT_LOCK=off turns the lock off.

Regression runs without an agent

An agent finds a path through your application once and saves it as a scenario — a JSON file. After that the scenario replays without an agent: fast, the same way every time, no tokens spent.

mcp-test-utils --check order-form.json     # validate the file, touch nothing
mcp-test-utils --run order-form.json       # run: report in the console and in order-form.report.json

• Exit code 0 — passed, 1 — a step failed, 2 — did not run: ready for a CI job after each build.
• On a failure you get a screenshot, the element tree and a hint: the scenario is stale or the application changed.
• An agent runs a scenario with run_scenario(path) and learns the format from get_usage_guide(section: "scenarios").
• Without a license key a scenario runs up to 50 steps (see License key).

Feedback

When an agent notices that something was missing in mcp-test-utils (a tool, a parameter, an unclear refusal, a workaround), it offers at the end of its answer to prepare a short suggestions file. After you agree it calls prepare_feedback: one Markdown file in Documents\mcp-test-utils feedback\ with a contents list at the top, the environment (version, OS, client, license status and its registered email), the agent's description, the failed steps of a report if needed, and session statistics. Emails, user names in paths, secrets, long numbers and tokens are masked; screenshots and element trees are never included. Check the contents list and attach the file to an email to JeenyJAI@gmail.com. The server sends nothing itself.

How It Works

MCP Test Utils is a JSON-RPC 2.0 server communicating over stdin/stdout. Any MCP-compatible client launches the binary, sends tool calls, and receives structured responses (text, base64 images). Tested with Claude Desktop.

The server uses native Windows APIs directly — Win32 GDI for screenshots, SendInput for mouse and keyboard, UI Automation COM API for element inspection, WinRT Windows.Media.Ocr for text recognition. File search uses the ripgrep engine (grep-regex, grep-searcher, ignore) — cross-platform, no external dependencies. No PowerShell, no external tools, no network access (except the update check you start in the tray window).

Use Cases

• Automated QA — agent navigates the app, clicks through flows, takes screenshots at each step, writes a test report
• Regression runs — replay saved scenarios after each build, from a script or a CI job, without an agent
• Desktop automation — fill forms, copy data between windows, run workflows
• Accessibility audit — scan UI Automation tree for missing labels or roles
• Visual regression — screenshot comparison across releases
• Data extraction — read document text through UI Automation, or OCR text from applications that don't expose it
• Code search — find patterns across multiple projects without leaving the agent session

Security

• Responds only to requests from the MCP client
• Opens no network ports
• Writes nothing to disk except opt-in logging, scenario reports (next to the scenario file or in --out), the suggestions file of prepare_feedback (on request), the license saved by --set-license (%APPDATA%\mcp-test-utils\license.txt), the tray window settings (%LOCALAPPDATA%\mcp-test-utils\notify.json), the input lock state (%LOCALAPPDATA%\mcp-test-utils\input-lock.json) and an update you install from the tray window (next to the running exe)
• Sends no data externally; goes online only when you click Check for updates (and Download and install) in the tray window — an agent's tool call never does, and only a file signed by the author is installed
• Holds the user's keys and mouse buttons only during a call, batch or scenario run that sends input — Esc releases them at once
• Screenshots capture the entire screen — make sure no sensitive information is visible
• File search is sandboxed — only directories in MCP_SEARCH_DIRS are accessible

License key

All tools are free. A license key only lifts the 50-step limit of scenario runs.

For now keys are given through early access: the first 30 users get a free one-year key in exchange for short feedback after the first month — write to JeenyJAI@gmail.com with your email and the machine code of your computer. A key is bound to that computer: your agent sees the code in the second line of get_usage_guide, or print it yourself:

mcp-test-utils --machine-id

Register the key once on that computer:

mcp-test-utils --set-license <email> <key>

Reinstalling Windows or replacing the board alone keeps the key; a new computer needs a new key — write again.

A sealed scenario runs anywhere without the limit — only that file, as sealed. On the licensed computer mcp-test-utils --seal order-form.json writes a seal into the file; a CI agent or a colleague without a key then runs it in full. Any change of its steps (or of the fragments it includes) breaks the seal — seal it again on the licensed computer.

Support us

If you find it useful — jeenyjai.github.io

License

Copyright 2026 JeenyJAI. All rights reserved.

🚀 Created with Claude