AgentViewport

AgentViewport is a bridge tool that turns your local desktop into a browser-based viewport and an MCP (Model Context Protocol) Server. It enables AI agents (like Claude Desktop, Cursor, or custom agents) to "see" your screen and interact with it (click, type, drag) via a standardized protocol using their embedded browser tools.

Features

• MCP Server: Exposes get_screenshot, mouse_click, key_type, and more to AI agents.

• Low Latency Viewport: Streams your desktop to http://localhost:3000 for remote viewing or debugging.

• System Tray Integration: Background execution with a convenient tray menu.

• Safety Mode: Emergency kill-switch (defaults to Tray Exit).

• Portable: Can be built into a standalone .exe with bundled dependencies.

Related MCP server: servo-mcp

Prerequisites

• Node.js 20+ - Download from nodejs.org

• Windows 10/11 - Currently Windows-only (uses native Windows APIs for screen capture and input simulation)

• npm - Comes with Node.js

Installation

Option A: Run from Source

1. Clone the repository:

   git clone https://github.com/guybnd/agent-viewport.git
   cd agent-viewport

2. Install dependencies:

   npm install

3. Run the application:

   npm start

Option B: Build Standalone Executable

1. Install dependencies (if not already done):

   npm install

2. Build the executable:

   npm run build

3. Copy runtime dependencies:

   node copy_assets.js

4. Run from the dist folder:

   .\dist\AgentViewport.exe

Configuration

Using with Claude Desktop (MCP)

To let Claude "see" your computer, add AgentViewport to your claude_desktop_config.json:

Windows Config Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-viewport": {
      "command": "node",
      "args": ["C:\\path\\to\\agent-viewport\\server.js"]
    }
  }
}

If using the built .exe:

{
  "mcpServers": {
    "agent-viewport": {
      "command": "C:\\path\\to\\AgentViewport.exe",
      "args": []
    }
  }
}

Application Config

A configuration file is automatically created at %AppData%\AgentViewport\agent-viewport.config.json. You can modify:

• port: Web server port (Default: 3000)

• targetWidth: Screenshot resizing width (Default: 2560)

• fps: Streaming FPS (Default: 10)

• jpegQuality: Compression quality (Default: 70)

Tools Available to Agents

Security & Privacy

• Local Execution: The server binds to localhost:3000 by default. It is not accessible from the internet unless you explicitly use a tunnel or port forwarding.

• MCP Security: The MCP server communicates via stdio (Standard Input/Output), which is a local-only transport managed by your AI client (e.g., Claude Desktop).

• No Cloud Processing: Screenshots and input data are processed entirely on your machine. No data is sent to external servers by this tool.

• Transparency: This project is open-source. You can inspect server.js to see exactly how screenshots are captured and how mouse/keyboard inputs are handled.

Troubleshooting

Acknowledgements

This project is made possible by these incredible open-source libraries:

• RobotJS - Desktop automation.

• Model Context Protocol SDK - MCP server framework.

• Sharp - High-performance image processing.

• screenshot-desktop - Cross-platform screenshots.

• Socket.io - Real-time viewport streaming.

• SysTray2 - System tray integration.

License

MIT