segentic-lab/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
**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
Prerequisites
- Python 3.11+
- Playwright + Chromium browser
Installation (Local)
Quick install (Debian/Ubuntu)
One command — clone and install:
Fully unattended (no confirmation prompts):
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