peeko

Let Claude see your mobile app. Peeko is an MCP server that hands Claude screenshots of your iOS Simulator, Android emulator, or a physical Android device plugged into USB.

It is deliberately read-only. Peeko observes; it never taps, swipes, or types. Claude can look at what your app is rendering and reason about it — a layout that broke, a state you can't reproduce in words, a diff between what you meant and what shipped — without ever touching the device.

You:    Why does the login screen look wrong on the iPhone 16?
Claude: [screenshot_ios] The "Continue" button is clipped — its container has a
        fixed height of 44pt but the text wraps to two lines at this width.

Requirements

iOS support is macOS-only, and always will be: it relies on xcrun simctl, which ships with Xcode and does not exist on other operating systems. On Linux and Windows the three iOS tools return a clear error and the Android tools work normally.

Node.js 18 or later is required.

Installing the prerequisites

• Xcode command line tools (macOS, for iOS): xcode-select --install

• Android platform tools (all platforms, for Android):

  • macOS — brew install --cask android-platform-tools

  • Linux — apt install android-tools-adb (or your distribution's equivalent)

  • Windows — winget install Google.PlatformTools

Make sure adb ends up on your PATH. Peeko tells you so explicitly if it doesn't.

Related MCP server: macOS Simulator MCP Server

Install

Every agent at once

add-mcp detects the agents installed on your machine and writes the right config for each one:

npx add-mcp peeko@latest

Add -g to install globally rather than for the current project, and -a to target specific agents — claude-code, claude-desktop, codex, cursor, gemini-cli, goose, opencode, vscode, zed.

Claude Code

As a plugin, which needs no MCP configuration at all:

claude plugin marketplace add rocktane/peeko
claude plugin install peeko@peeko

Or as a plain MCP server:

claude mcp add peeko -- npx -y peeko@latest

Codex

codex mcp add peeko -- npx -y peeko@latest

opencode

opencode is configured by file only. In opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "peeko": {
      "type": "local",
      "command": ["npx", "-y", "peeko@latest"],
      "enabled": true
    }
  }
}

Cursor, Claude Desktop, and other MCP clients

Add this to your client's MCP configuration:

{
  "mcpServers": {
    "peeko": {
      "command": "npx",
      "args": ["-y", "peeko@latest"]
    }
  }
}

Tools

Every tool takes an optional device_id — a Simulator UDID on iOS, a device serial on Android. Omit it and Peeko picks the first available device, which is what you want when only one is running.

Usage

Boot a simulator or emulator, then just ask:

Take a screenshot of the simulator and tell me if the spacing looks right.

Compare the Android and iOS home screens side by side.

The list is empty on Android but not on iOS — screenshot both and tell me what differs.

Privacy

Screenshots are sent to the model, exactly like any other tool result. Whatever is on the device screen goes with them — test accounts, tokens in a debug overlay, a customer's real data if you are pointed at production. Peeko cannot tell the difference. Check what's on screen before you ask for a capture.

Peeko never writes to the device, never installs anything on it, and never sends data anywhere other than the MCP client that invoked it.

Development

Peeko is written in TypeScript. It runs on Node in production, and uses Bun as the dev runtime and test runner.

bun install
bun test           # unit tests on the parsers
bun run typecheck  # tsc --noEmit
bun run build      # tsc → dist/
bun run start      # run the server from source over stdio

The repo ships a .mcp.json that points at src/index.ts, so opening it in Claude Code gives you the server you're editing, live.

Layout

src/
  index.ts            MCP server: tool registration and stdio transport
  tools/              one handler per tool; formats MCP results
  platforms/
    ios.ts            xcrun simctl
    android.ts        adb
    exec.ts           subprocess helper; turns ENOENT into actionable errors
    png.ts            reads dimensions from a PNG's IHDR chunk
test/
  parsers.test.ts     covers the pure parsing functions

The device-facing code shells out to xcrun and adb, so it can't be unit-tested without hardware. The parsers it depends on are pure functions and are tested directly — including CRLF handling, which is what makes Android work on Windows.

Contributing

Issues and pull requests are welcome. Please run bun test and bun run typecheck before opening a PR; CI runs both on Linux, macOS and Windows.

License

MIT © Yohan (@rocktane)