screen-mcp-server

Lightweight MCP server that gives AI coding assistants the ability to see your screen in real time. Built for multi-monitor setups on Windows, works with Claude Code and any MCP-compatible client.

Features

• Multi-monitor capture — list monitors, screenshot any display or all at once
• Built-in scheduling — fixed or random delay before capture (no external sleep/cron needed)
• PDF text extraction — load study materials or documentation into context
• Answer logging — persist Q&A pairs to JSON for later search and retrieval
• Single file, minimal deps — just mss, Pillow, PyMuPDF and mcp[cli]

Quick start

1. Install dependencies

pip install "mcp[cli]" mss Pillow PyMuPDF

2. Register with Claude Code

claude mcp add -s user -t stdio screen-mcp -- python /path/to/server.py

3. Restart Claude Code

The server connects via stdio and exposes its tools automatically.

Tools

Tool	Description
list_monitors	List all monitors with resolution and position
take_screenshot	Capture a specific monitor (supports delay / random delay)
read_pdf	Extract full text from a PDF file
list_pdfs	List PDF files in the working directory
log_answer	Save a question-answer pair to a local JSON log
search_answers	Search previously logged answers by keyword

Screenshot with random delay

The take_screenshot tool accepts optional timing parameters so the AI assistant can self-schedule periodic captures without requiring shell access:

take_screenshot(monitor=2, delay_min=30, delay_max=60)

This waits a random 30–60 seconds before capturing, which is useful for hands-free monitoring workflows.

Example: Claude Code integration

Add this to your project's CLAUDE.md to let Claude automatically monitor your screen:

## Screen monitoring

- Use `list_monitors()` to see available displays
- Use `take_screenshot(monitor=2)` for an instant capture
- Use `take_screenshot(monitor=2, delay_min=30, delay_max=60)` for periodic monitoring
- Use `read_pdf("notes.pdf")` to load reference materials

Configuration

The server is registered in ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "screen-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Requirements

• Python 3.10+
• Windows / macOS / Linux (mss is cross-platform)
• Claude Code or any MCP-compatible client

License

MIT