Pathlight MCP

The zero-code desktop + web MCP server. Connect any AI agent to native desktop applications and web browsers in 30 seconds — no configuration, no API keys required.

Pathlight MCP turns any desktop application or web browser into a navigable accessibility tree that AI agents can see, click, type into, and control — through standard MCP tool calls. It works where Playwright cannot: native apps, system dialogs, legacy software, control panels, and any window that responds to OS accessibility APIs. It also connects to Chromium-based browsers via the Chrome DevTools Protocol for web accessibility automation.

New to MCP? The Model Context Protocol is the standard way AI agents interact with external tools. If your client supports MCP servers, it supports Pathlight MCP.

How Agents Connect

Pathlight MCP uses the MCP stdio transport, which means any MCP-compatible client can connect by pointing at the pathlight-mcp command. No API keys, no web server, no browser extension.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pathlight-mcp": {
      "command": "pathlight-mcp",
      "args": []
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pathlight-mcp": {
      "command": "pathlight-mcp",
      "args": []
    }
  }
}

Windsurf

Add to .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "pathlight-mcp": {
      "command": "pathlight-mcp",
      "args": []
    }
  }
}

VS Code (Copilot / Continue / Cline)

Add to your VS Code MCP settings:

{
  "mcp": {
    "servers": {
      "pathlight-mcp": {
        "command": "pathlight-mcp",
        "args": []
      }
    }
  }
}

Any MCP Client

Pathlight MCP is a standard MCP stdio server. Point any MCP client at the pathlight-mcp command:

pathlight-mcp                 # auto-detect platform, start MCP server
pathlight-mcp --backend mock  # use mock backend for testing (no desktop needed)

Install

That's it. pip install pathlight-mcp + one JSON config block above = done. No API keys, no browser, no extra setup.

pip install pathlight-mcp

# With platform support (optional — auto-detected at runtime)
pip install "pathlight-mcp[windows]"    # Windows (comtypes)
# Linux X11 support (python-xlib) is included automatically on Linux

git clone https://github.com/Mikenahh92/Guidewire.git
cd Guidewire
pip install -e ".[dev]"

Usage Examples

Every example below is an MCP tool call. Your agent makes these calls automatically — you just describe what you want done.

See what's on screen

# 1. List all open windows — the agent picks the one it needs
windows = await desktop.list_windows()
# → [{"title": "Untitled - Notepad", "ref": "w1"}, ...]

# 2. Snapshot the accessibility tree of a window (like a DOM, but for native apps)
tree = await desktop.snapshot(window_ref="w1")
# → {"ref": "e1", "role": "window", "name": "Untitled - Notepad",
#    "children": [{"ref": "e2", "role": "text_edit", ...}]}

Find and interact with elements

# Find a text field by role — no CSS selectors or XPath needed
elements = await desktop.find(window_ref="w1", role="text_edit")
# → [{"ref": "e3", "role": "text_edit", "name": "Text Editor"}]

# Type into it — just like a human would
await desktop.type_text(element_ref="e3", text="Hello from Pathlight MCP!")

# Find and click a button by name
buttons = await desktop.find(window_ref="w1", name="Save")
await desktop.click(element_ref="e4")  # clicks the Save button

Wait for something to appear

# Block until a "Save As" dialog appears (up to 10 seconds, checking every 500ms)
await desktop.wait_for(
    condition={"type": "element_appears", "role": "dialog", "name": "Save As"},
    timeout_ms=10000,
    interval_ms=500
)

Automate a multi-step workflow

# Batch 2–20 actions into a single call — faster and more reliable
await desktop.multi_action(actions=[
    {"tool": "click", "element_ref": "e5"},                          # open menu
    {"tool": "type_text", "element_ref": "e6", "text": "report.pdf"}, # type filename
    {"tool": "click", "element_ref": "e7"}                           # confirm save
])

Work with tables and trees

# Read table dimensions and headers
info = await desktop.get_table_info(element_ref="t1", action="info")
# → {"rows": 50, "columns": 4, "headers": ["Name", "Size", "Type", "Modified"]}

# Read a specific cell
cell = await desktop.get_table_info(element_ref="t1", action="read_cell", row=0, col=0)
# → {"value": "report.pdf"}

# Expand a tree node and read its children
tree = await desktop.get_tree_info(element_ref="e8", action="expand")

MCP Tools

All 17 tools are available under the desktop. namespace immediately after connection — no setup required.

Window Management

Element Inspection

Interaction

Clipboard

Orchestration

Supported Platforms

All backends implement the same abstract interface, providing identical tool behavior regardless of platform.

Web Backend Setup

The web backend connects to any Chromium-based browser launched with --remote-debugging-port. See the Web Backend Setup Guide for browser-specific instructions.

# Launch Chrome with remote debugging
google-chrome --remote-debugging-port=9222

from pathlight_mcp.backends.web import WebBackend

backend = WebBackend(host="localhost", port=9222)
backend.connect()
windows = backend.list_windows()  # lists open browser tabs

Safety Model

Every action is automatically classified into one of three risk tiers — your agent can use this to gate dangerous operations behind user confirmation.

Additional privacy controls automatically detect password fields, redact sensitive values, and support app-level denylisting.

Configuration

Pathlight MCP auto-detects your platform at startup. One optional flag:

Testing

Pathlight MCP has a comprehensive test suite covering unit, integration, and end-to-end scenarios:

# Run full suite
pytest

# Run with coverage
pytest --cov=pathlight-mcp

# Run only unit tests (no desktop needed)
pytest -k "not integration"

Roadmap

Contributing

See CONTRIBUTING.md for development setup, architecture details, and the tool authoring guide.

For release and rollback procedures, see RELEASING.md.

License

MIT — Copyright 2025–2026 Mikenahh92