PeepIt

Provides macOS screenshot capture and AI analysis via MCP with local or cloud AI providers.

typescript

1

GitHub Stars

typescript

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mantisware-peepit": {
      "command": "npx",
      "args": [
        "-y",
        "@mantisware/peepit-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
        "PEEPIT_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest"
      }
    }
  }
}

PeepIt MCP is a macOS-centric server that lets AI agents observe and analyze your screen content by capturing screenshots, listing running applications, and performing AI-powered analyses. It enables you to orchestrate AI vision workflows locally or with cloud providers while keeping control over privacy and permissions.

How to use

To use PeepIt MCP, you run the server locally and connect an MCP client. You configure one or more MCP endpoints that the client can talk to, then issue tool calls from your client to capture screenshots, list windows or apps, and ask questions about images.

How to install

Prerequisites you need before installing PeepIt MCP are macOS 14.0+ (Sonoma or later) and Node.js 20.0+. You will also be prompted for Screen Recording permission when you first run the server.

Step 1: Install Node.js if it is not already installed. You can install it from a package manager or the official installer.

Step 2: Ensure you have a macOS Screen Recording permission enabled for the terminal or MCP client you will use.

Step 3: Add PeepIt MCP to your environment by using an MCP client configuration. The following stdio configurations illustrate running the MCP server via the npm-based wrapper, with the appropriate environment variables set for AI providers and API keys.

Step 4: Start the MCP server through your chosen client configuration and verify it initializes correctly.

Configuration and environment

PeepIt MCP is controlled via environment variables that select AI providers, set API keys, adjust logging, and define default save paths. You can configure these in the MCP client’s startup environment to tailor behavior to your workflow.

Important environment variables include PEEPIT_AI_PROVIDERS to choose AI models, OPENAI_API_KEY for cloud usage, and PEEPIT_LOG_LEVEL for logging verbosity.

Testing and debugging

Use the MCP inspector or direct CLI tests to validate server behavior. You can run test commands to verify provider availability and server status, and inspect logs when something goes wrong.

Security and permissions

PeepIt respects macOS security prompts and requires Screen Recording (and optionally Accessibility) permissions for reliable operation. Grant these permissions to the terminal or MCP client, then restart the app to apply changes.

Troubleshooting

If you encounter permission issues, ensure Screen Recording and Accessibility permissions are enabled for the correct applications. If the Swift CLI is unavailable, confirm the peepit-mcp binary exists and is executable. For AI analysis failures, verify your provider configuration and API keys, and check logs for details.

Notes and tips

You can run multiple MCP configurations for PeepIt, each with its own provider mix. For privacy, you can prefer local Ollama-based models or cloud providers as needed. The tool supports robust capture options and careful file-naming to prevent overwrites.

Available tools

image

Capture screenshots of the screen, an app, or a window with configurable targets and output formats.

list

List running applications, windows, and server status to help target captures and understand the current environment.

analyze

Submit a captured image to an AI model for analysis and obtain a textual response describing the content or answering questions.