# Screeny MCP Server

A **macOS-only MCP server** that enables LLMs to capture screenshots of specific application windows, providing visual context for development and debugging tasks.

> [!IMPORTANT]
> Requires **Screen Capture permission** - must be granted before running window approval setup. Read instructions below.

### Available Tools

- `listWindows` - Lists all approved application windows available for screenshot capture.

  - Only shows user approved windows

- `takeScreenshot` - Captures a screenshot of a specific window by its ID.
  - **Captures windows in background** - no need to bring window to front, but cannot capture minimized windows
  - **Provides actual pixel data** - full-fidelity image, not OCR or text extraction

### Resources

- `screeny://info` - Server information and configuration details

## Configuration

### Claude Desktop

1. Open Claude settings → Developer → Edit Config
2. Add configuration
3. **Restart Claude Desktop** after saving config

<details>
<summary><strong>Using uvx (recommended)</strong></summary>

```json
{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}
```

> **Note:** If you get a "spawn uvx ENOENT" error, replace `"uvx"` with the full path to uvx:
>
> ```bash
> which uvx  # Find your uvx path
> ```
>
> Then use that full path in the config (e.g., `"/opt/homebrew/bin/uvx"`).

</details>

<details>
<summary><strong>Using pipx installation</strong></summary>

First install with: `pipx install mcp-server-screeny`

```json
{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}
```

> **Note:** If you get an `ENOENT` error, replace `"mcp-server-screeny"` with the full path to the executable (find it with `which mcp-server-screeny` in your terminal).

</details>

### Cursor

1. Open Cursor settings → Tools & Integrations → MCP Tools
2. Add configuration
3. **Restart Cursor** after saving config

<details>
<summary><strong>Using uvx (recommended)</strong></summary>

```json
{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}
```

> **Note:** If you get a "spawn uvx ENOENT" error, replace `"uvx"` with the full path to uvx:
>
> ```bash
> which uvx  # Find your uvx path
> ```
>
> Then use that full path in the config (e.g., `"/opt/homebrew/bin/uvx"`).

</details>

<details>
<summary><strong>Using pipx installation</strong></summary>

First install with: `pipx install mcp-server-screeny`

```json
{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}
```

> **Note:** If you get an `ENOENT` error, replace `"mcp-server-screeny"` with the full path to the executable (find it with `which mcp-server-screeny` in your terminal).

</details>

## Setup

### 1. Grant Screen Capture Permission (Required)

**Important:** Grant permission before running window approval.

> **Note**: You need to grant Screen Capture permission to BOTH:
>
> 1. **Your Terminal application** (Terminal.app, iTerm2, etc.) - Required for running setup
> 2. **Your MCP host** (Claude Desktop, Cursor) - Required for taking screenshots
>
> To add them:
>
> 1. Open **System Settings** > **Privacy & Security** > **Screen & System Audio Recording**
> 2. Click the **"+"** button
> 3. Add your Terminal application AND your MCP host application
> 4. **Restart both applications** after granting permissions

### 2. Window Approval (Required)

After configuring your MCP client above, approve which windows can be captured.

**Choose your installation method:**

<details>
<summary><strong>If using uvx</strong></summary>

```bash
# Interactive approval
uvx mcp-server-screeny --setup

# Auto-approve all current windows
uvx mcp-server-screeny --setup --allow-all
```

</details>

<details>
<summary><strong>If using pip/pipx</strong></summary>

```bash
# Interactive approval
mcp-server-screeny --setup

# Auto-approve all current windows
mcp-server-screeny --setup --allow-all
```

</details>

Approvals are saved to `~/.screeny/approved_windows.json`. Re-run setup when you want to update the list of approved windows.

## Security & Privacy

- Only user-approved windows can be captured
- All processing stays local on your machine
- Screenshots are temporary and deleted immediately after use

## Troubleshooting

### Permission Issues

```bash
# Test window detection and permissions
mcp-server-screeny --debug

# Re-run setup if windows changed
mcp-server-screeny --setup
```

### Common Issues

**"spawn uvx ENOENT" error**

- Solution: Use the full path to uvx in your MCP config instead of just `"uvx"`
- Find path with: `which uvx`
- Example: `"/opt/homebrew/bin/uvx"` or `"/usr/local/bin/uvx"`

**"Quartz framework not available"**

- Solution: Install dependencies with `pip install -e .` or ensure internet connection for automatic installation

**"No approved windows found"**

- Solution: Run `mcp-server-screeny --setup` first

**"Screen Recording permission required" or "No windows found"**

- Solution: Grant Screen Recording permission in System Settings > Privacy & Security > Screen & System Audio Recording
  - Click "+" button and manually add your MCP host (Claude Desktop, Cursor, etc.)
  - Restart your MCP host application after granting permissions
- Try running setup again after granting permissions

## Contributing

Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements.

This is my first MCP server project - if you encounter any bugs, please open an issue and I'll do my best to fix them!

<details>
<summary><strong>Why I Built This</strong></summary>

I created this tool to streamline my mobile development workflow. I was tired of
manually taking screenshots repeatedly to describe UI issues while coding. Now,
with Screeny, my LLM can directly capture screenshots of my iOS simulator,
allowing them to see their UI changes and iterate on the design in a continuous
loop. I'm excited to see how others will use this!

</details>

## Requirements

- Python 3.10+
- macOS (uses Quartz framework)

## License

MIT License
