MCP Test Utils

MCP Test Utils

100% AI Code · Human Reviewed

  

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.

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.

Demo

10 tasks. One take. Watch on YouTube →


MCP Test Utils vs Anthropic Computer Use

Claude Cowork now includes built-in Computer Use — Claude takes screenshots and clicks through interfaces visually. It works with zero setup. MCP Test Utils takes a different approach: instead of guessing where to click from a screenshot, it reads the actual UI structure through Windows APIs.

| | MCP Test Utils | Computer Use | |---|---|---| | Click precision | Exact — UI Automation API | Visual estimate from screenshot | | Speed & token cost | Fast, low cost — text responses | Slower, costly — image on every step | | UI structure | Full tree: roles, states, coordinates | Not available | | OCR | Word-level coordinates, multi-language | Not available (model vision only) | | Window management | API-based, window-relative coords | Visual navigation | | File search | Ripgrep engine built-in | Not available | | Session logging | JSONL + screenshots | Not available | | Visual analysis | ✅ Same Claude model, full-res 1:1 | ✅ Same Claude model | | Setup | Download binary, add to config | Built-in, one toggle | | Mobile / Dispatch | — | ✅ Tasks from phone | | Cross-platform | Windows (macOS/Linux planned) | macOS + Windows |

MCP Test Utils is faster, more precise, and cheaper per action. Computer Use is easier to start and works across platforms. They complement each other.

Platforms

| Platform | Status | |---|---| | Windows x64 | ✅ Full support | | macOS arm64 | ⏳ Planned | | Linux x64 | ⏳ Planned |

Tools (19)

Vision

| Tool | Description | |---|---| | take_screenshot | Screenshot of the entire desktop with configurable quality | | take_window_screenshot | Screenshot of a specific window (screen or window capture mode) | | read_screen_text | OCR the entire screen (Windows.Media.Ocr) | | read_region_text | OCR a screen region with precise word coordinates |

Window Management

| Tool | Description | |---|---| | list_windows | List windows with id, title, app, position, size, minimized, focused | | focus_window | Bring a window to front, restore if minimized |

Input

| Tool | Description | |---|---| | mouse_click | Click (left / right / middle) at screen or window-relative coordinates | | mouse_move | Move cursor to a point | | mouse_drag | Drag from point A to point B | | mouse_scroll | Scroll the mouse wheel | | keyboard_type | Type text (full Unicode — Latin, Cyrillic, CJK, emoji) | | keyboard_press | Press a key (Enter, Tab, F1–F12, arrows, etc.) | | keyboard_shortcut | Key combinations (Ctrl+S, Alt+F4, Ctrl+Shift+P, etc.) |

Structured UI Access

| Tool | Description | |---|---| | list_ui_elements | UI Automation tree — buttons, fields, menus with exact coordinates |

File Search

| Tool | Description | |---|---| | search_in_files | Search text or regex in files within allowed directories (like VS Code Find in Files) | | find_files | Find files and directories by name pattern (glob), like "Go to File" |

Agent Guide

| Tool | Description | |---|---| | get_usage_guide | Compact workflow guide for LLM agents — precision clicking, coordinate metadata, quality tips |

Session Logging

| Tool | Description | |---|---| | enable_logging | Start recording tool calls to JSONL + screenshots (opt-in) | | disable_logging | Stop recording, get session stats |

Installation

1. Download the binary from Releases.
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"
    }
  }
}

1. Restart Claude Desktop.
2. 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:

| Preset | Scale | Format | Use Case | |---|---|---|---| | full | 100% | JPEG q90 | Maximum detail | | standard | 50% | JPEG q70 | Balanced (default) | | compact | 50% | PNG | When PNG is needed | | minimal | 25% | Grayscale | Lowest token cost | | custom | 10–100% | JPEG / PNG / Grayscale | Full control |

Environment Variables

| Variable | Description | Default | |---|---|---| | MCP_LOG_DIR | Path for log sessions. Without it, logging tools are hidden | — | | MCP_LOG_MAX_MB | Session size limit (warning on exceed) | 500 | | MCP_LOG_RETAIN_DAYS | Auto-delete sessions older than N days. 0 to disable | 30 | | MCP_SEARCH_DIRS | Allowed directories for search_in_files (; on Windows, : on macOS/Linux). Without it, the tool is hidden | — |

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.

Use Cases

• Automated QA — agent navigates the app, clicks through flows, takes screenshots at each step, writes a test report
• 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 — OCR text from applications that don't expose APIs
• 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)
• Sends no data externally
• Screenshots capture the entire screen — make sure no sensitive information is visible
• File search is sandboxed — only directories in MCP_SEARCH_DIRS are accessible

Support us

Free and unrestricted. If you find it useful — jeenyjai.github.io

License

Copyright 2026 JeenyJAI. All rights reserved.

<!-- mcp-name: io.github.JeenyJAI/mcp-test-utils -->

---

🚀 Created with Claude