# screen-mcp-server

Lightweight [MCP](https://modelcontextprotocol.io/) 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

```bash
pip install "mcp[cli]" mss Pillow PyMuPDF
```

### 2. Register with Claude Code

```bash
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:

```markdown
## 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`:

```json
{
  "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