# peeko

**Let Claude see your mobile app.** Peeko is an [MCP](https://modelcontextprotocol.io) 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

| Platform | iOS Simulators | Android devices & emulators |
|---|---|---|
| macOS | ✅ Xcode required | ✅ `adb` required |
| Linux | ❌ not possible | ✅ `adb` required |
| Windows | ❌ not possible | ✅ `adb` required |

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.

## Install

### Every agent at once

[`add-mcp`](https://github.com/neondatabase-labs/add-mcp) detects the agents installed on your machine and writes the right config for each one:

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

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

Or as a plain MCP server:

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

### Codex

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

### opencode

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

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

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

## Tools

| Tool | What it does |
|---|---|
| `list_ios_simulators` | Lists every booted iOS Simulator, with its UDID. |
| `screenshot_ios` | Returns a PNG of a Simulator's screen. |
| `info_ios` | Name, OS version and screen size of a Simulator. |
| `list_android_emulators` | Lists every connected Android device and emulator. |
| `screenshot_android` | Returns a PNG of a device's screen. |
| `info_android` | Name, OS version and screen size of a device. |

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](https://bun.sh) as the dev runtime and test runner.

```bash
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](https://github.com/rocktane))