periscope-mcp

An MCP server that gives AI agents 74 Playwright tools to QA, test, and analyze web apps — static sites, SPAs, and apps behind a login — returning hard verdicts, not screenshots to squint at. Not a thin wrapper around browser APIs; the tools are shaped around how agents actually work:

• Hard results, not screenshot-squinting — assert_condition returns passed: true/false with the actual value; checks return structured issues.
• One call instead of ten — auto_fill_form detects, infers, and fills a whole form; interact_and_test batches 25 action types with checks; test_project crawls and audits an entire site.
• Real web-app testing — persistent authenticated sessions (form/basic/ cookie auth, plus a visible interactive login for 2FA/SSO/CAPTCHA that then runs headless), multi-step flows, network mocking, state snapshots, and real INP measured from the interactions it drives.
• Honest responses — failures say what happened and what to do next (expired session vs. browser crash vs. eviction); silent no-ops like ignored drags come back flagged, not as fake success.
• Debugging built in — captured API response bodies, console/network logs, network mocking, and state snapshots/diffs, no setup calls needed.
• Audits agents can't get from a browser binding — accessibility, SEO, and GEO/agentic-search readiness (robots.txt AI-crawler access, llms.txt, WebMCP), plus real Lighthouse.

Playwright + headless Chrome underneath; site crawling, responsive testing, and screenshot diffing on top. Works with any MCP client — Claude Code, Codex, Cursor, Windsurf, Gemini CLI, custom agents, or anything else that speaks MCP over stdio.

Why not just playwright-mcp?

playwright-mcp is excellent at what it is: general browser control over MCP, with tools that mirror Playwright's own API. If the job is "browse this site, click around, extract something," use it.

Periscope exists for a different job: testing and auditing a site or web app, then reporting findings — and its tools encode the testing knowledge an agent would otherwise have to reinvent every session:

| | Raw browser control | Periscope | |---|---|---| | Verifying an outcome | Read a screenshot or DOM dump and judge | assert_condition → hard passed: true/false + actual value | | Filling a form | One call per field, agent invents test data | auto_fill_form — detects fields, infers realistic data, reports per-field failures | | Auth | Re-login by scripting clicks each session | Projects persist form/basic/cookie auth; sessions share the logged-in context | | Site-wide audit | Loop pages manually | test_project — crawl + accessibility/SEO/GEO/visual/functionality checks + saved report | | Diagnosing a broken page | Ask for logs, replay requests | Response bodies, console, and network are captured automatically; mock APIs with intercept_network | | Silent failures | Drag "succeeds," nothing moved | Flagged in the result, with the recovery path spelled out | | AI-readiness audits | — | robots.txt AI-crawler access, llms.txt, WebMCP annotations, JSON-LD, plus real Lighthouse scores |

The two aren't rivals — an agent can happily use playwright-mcp for browsing tasks and Periscope when it's wearing the QA hat. Periscope's design bets are simply about that hat: fewer, higher-level calls; structured verdicts instead of raw page state; and errors written to tell the agent what to do next.

Architecture

MCP client (AI agent)  -->  MCP Server (stdio)  -->  Playwright (Headless Chrome)
                                 |                         |
                                 +-- Projects (JSON)       +-- Persistent Sessions
                                 +-- Screenshots (PNG)     +-- Network Interception
                                 +-- Reports (JSON)        +-- Device Emulation
                                 +-- Videos (WebM)

How it works: your MCP client connects to this server over stdio. The server exposes 74 tools the agent can call to create projects, configure authentication, crawl websites, run static checks, and interactively test web applications using persistent browser sessions. Results (JSON + screenshots + videos) are returned to the agent for analysis.

Project Structure

periscope-mcp/
├── server.py              # MCP server entry point (stdio wiring + dispatch)
├── tool_schemas.py        # All 74 MCP tool definitions (schemas)
├── runtime.py             # Shared singletons (project store, sessions, browser)
├── coercion.py            # Argument coercion for MCP clients with stale schemas
├── handlers/              # Tool handlers, grouped by category
│   ├── registry.py        # @tool(name) decorator + HANDLERS registry
│   ├── projects.py        # create/list/get/delete project
│   ├── auth.py            # form login, basic auth, cookies, copy_auth
│   ├── static_testing.py  # test_url, crawl, test_project, reports, responsive
│   ├── session_tools.py   # open/close/list sessions, viewport, history
│   ├── interactive.py     # click, fill, steps, element queries, dialogs
│   ├── analysis.py        # forms, links, keyboard nav, tables, toasts, contrast
│   ├── advanced.py        # network mocking, storage, iframes, emulation, recording
│   ├── agent_speed.py     # assertions, smart find, auto-fill, snapshots
│   ├── web.py             # web_search, web_fetch
│   ├── discovery.py       # describe_tools catalog
│   └── system.py          # periscope_system: status, self-update, agents_md
├── tester.py              # Playwright browser control + test orchestration
├── crawler.py             # Page discovery (BFS crawl, same-domain only)
├── projects.py            # Project CRUD + auth config storage
├── auth.py                # Authentication handlers (form, basic, cookies)
├── sessions.py            # SessionManager + PageSession — persistent page lifecycle
├── interactions.py        # Interaction primitives (click, fill, execute_steps)
├── utils.py               # Screenshot comparison (Pillow pixel diff)
├── config.py              # Global settings (timeouts, paths, session limits)
├── checks/
│   ├── visual.py          # Broken images, favicon, overflow, small text
│   ├── accessibility.py   # Alt text, labels, headings, lang, ARIA, keyboard nav
│   ├── functionality.py   # Broken links, forms, SEO, performance, link checker
│   └── geo.py             # GEO/agentic search: robots.txt AI crawlers, llms.txt, WebMCP, JSON-LD
├── tests/                 # Unit tests (no browser) + tests/e2e/ (real browser + fixture pages)
├── data/                  # Created at runtime (gitignored — contains credentials)
├── Dockerfile
├── docker-compose.yml
└── .mcp.json.example      # MCP registration template (copy to .mcp.json)

Prerequisites

• Python 3.11+
• Playwright + Chromium browser

Installation (Local)

Quick install (Debian/Ubuntu)

One command — clone and install:

git clone https://github.com/segentic-lab/periscope-mcp.git && cd periscope-mcp && ./install.sh

Fully unattended (no confirmation prompts):

git clone https://github.com/segentic-lab/periscope-mcp.git && cd periscope-mcp && ./install.sh -y

Already cloned? Just run ./install.sh from the repo directory.

The script installs apt prerequisites, creates the venv, installs Python dependencies and Playwright's Chromium, runs a headless self-test, and generates mcp-config.json with the correct absolute paths for this install (copy or merge it into your project's .mcp.json). Useful flags:

• ./install.sh --system-chromium — use an existing Chromium/Chrome (sets CHROMIUM_PATH) instead of downloading Playwright's build
• ./install.sh --skip-deps — never touch apt / use sudo
• ./install.sh -y — non-interactive (no confirmation prompts)

On any other platform the script doesn't modify your system — it prints the exact commands to run for your OS (./install.sh --manual macos|fedora|arch|suse|windows to pick explicitly).

Updating

./update.sh

Pulls the latest source from GitHub (git pull --ff-only) and refreshes the install: Python dependencies, Playwright browser (kept on system Chromium if that's what the install uses), the registry + headless-launch self-test, and a regenerated mcp-config.json. Works on any platform with an existing install. Your data/ directory (projects, credentials, screenshots, reports) is never touched.

• ./update.sh --force — stash local modifications to tracked files first (recover with git stash pop)
• ./update.sh --full — also re-check apt prerequisites on Debian/Ubuntu (uses sudo)

If you have local modifications, the script refuses and lists them instead of overwriting.

Manual install

# Clone the repo
cd periscope-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install Chromium for Playwright
playwright install chromium

Installation (Docker)

docker compose up -d

See Docker Deployment section below.

Connecting an MCP Client

Periscope is a standard stdio MCP server: point any MCP client at venv/bin/python server.py and you're done. ./install.sh generates mcp-config.json with the correct absolute paths for your machine; most clients accept that shape directly:

{
  "mcpServers": {
    "periscope": {
      "command": "/path/to/periscope-mcp/venv/bin/python",
      "args": ["/path/to/periscope-mcp/server.py"]
    }
  }
}

Client-specific examples:

• Claude Code — copy the config into the project as .mcp.json (cp .mcp.json.example .mcp.json and adjust paths), or run claude mcp add periscope -- /path/to/venv/bin/python /path/to/server.py
• Cursor / Windsurf — add the block above to ~/.cursor/mcp.json / ~/.codeium/windsurf/mcp_config.json
• Codex CLI — add to ~/.codex/config.toml: [mcp_servers.periscope] with command and args as above
• Custom agents — any MCP SDK client can spawn the server over stdio with the same command and args

After configuring, restart your client.

Teaching your agent to use the tools

Two options, depending on your agent:

• Claude Code (recommended): install the skill. SKILL.md (repo root; also exposed at skills/periscope/ in the Claude Code skill layout) is a Claude Code skill — it auto-triggers on web-testing tasks and loads a distilled operating guide (workflow decision table + the pitfalls) only when needed, costing ~0 context otherwise:

  ln -s "$(pwd)/skills/periscope" ~/.claude/skills/periscope
  

  A symlink keeps it current with ./update.sh (copy the folder instead if you prefer a frozen version).

• Any other MCP client: paste the guide. AGENTS.md contains a ready-made system-prompt block — workflows, tool-selection guidance, and known pitfalls. Paste its contents into your agent's system prompt (or custom instructions).

Either way, the agent can always fetch the current full guide from the running server via periscope_system(action="agents_md") and the complete catalog via describe_tools().

MCP Tools Reference (74 tools)

Project Management (4 tools)

| Tool | Description | Required Params | |------|-------------|-----------------| | create_project | Create a new testing project | name, base_url | | list_projects | List all projects | (none) | | get_project | Get project details | name | | delete_project | Delete project + data | name |

Authentication (7 tools)

| Tool | Description | Required Params | |------|-------------|-----------------| | set_form_login | Configure