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:
Web-app QA for AI agents: 73 Playwright tools — auth, E2E, a11y/SEO/GEO, Web Vitals + Lighthouse
2026-11-10
ดาว
—
เครื่องมือ
—
อัปไทม์
—
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
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.
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.
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.
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:
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:
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 username/password form login
project, login_url, username, password
set_basic_auth
Configure HTTP Basic Auth
project, username, password
set_cookies
Inject session cookies
project, cookies (array)
login_project
Execute login using configured auth
project
interactive_login
Open a visible window to log in by hand (2FA/SSO/CAPTCHA), then save_login
project
save_login
Capture the manual-login session; the project then runs authenticated + headless
project
copy_auth
Copy auth config + session state between projects
from_project, to_project
For logins that can't be automated — 2FA/MFA, SSO/OAuth redirects, CAPTCHA, magic
links — use interactive_login (opens a real browser window; requires a display
on the server), complete the login yourself, then save_login. It captures the
authenticated session (cookies + localStorage) into the project, and every
future headless session reuses it. Re-run when the session expires (Periscope
flags that automatically — see the auth-expiry detection in test_project).
Static Testing (3 tools)
Tool
Description
Required Params
test_url
Test a single URL (screenshot + checks)
url
crawl_project
Discover all pages from base URL
project
test_project
Full audit: crawl + test all pages
project
Results (4 tools)
Tool
Description
Required Params
get_screenshot
Get screenshot file path
project, url
list_reports
List saved test reports
(optional: project)
get_report
Read a report file
report_path
session_report
HTML+PDF dossier of every tool call this run — args (redacted), verdicts, timings, screenshots
JSON-LD structured data: missing or unparseable blocks
noindex via robots meta orX-Robots-Tag response header
robots.txt blocking search engine crawlers (Googlebot, Bingbot, DuckDuckBot, ...) — error if all are blocked
Site-wide (via test_project): duplicate titles / meta descriptions across pages, reported under site_issues
GEO / Agentic Search (checks/geo.py -> check_geo)
Generative Engine Optimization — is the site readable and usable by AI crawlers, answer engines, and in-browser agents:
robots.txt blocking AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, and 11 more)
llms.txt presence and format compliance (Markdown with at least one H1)
WebMCP integration: declarative <form toolname> annotations present and complete (tooldescription), form coverage ratio, and — when the browser exposes document.modelContext — registered tool enumeration with schema/name/description validation
JSON-LD structured data presence (what answer engines cite from)
robots.txt and llms.txt are fetched once per origin and cached for the server's lifetime.
Core Web Vitals (lab values via buffered PerformanceObserver): Largest Contentful Paint (ms), Cumulative Layout Shift, Total Blocking Time approximation from long tasks (+ long-task count)
Interaction to Next Paint (INP) — interaction_to_next_paint_ms: the real INP, measured from Event Timing entries for the interactions Periscope drives (null until you've interacted). This is a genuine field-style measurement, not the TBT lab proxy — Lighthouse can't produce INP in lab mode at all.
Resource count
Total transfer size (bytes / KB)
For scored, Lighthouse-official metrics use the run_lighthouse tool — it runs the real Lighthouse CLI (requires Node.js) and returns 0-100 category scores, official Core Web Vitals, and failed audits, saving the full JSON report to data/reports/.
INP time series (get_interaction_log)
Because Periscope drives real interactions, it can log each one's INP over an
extended interactive test. get_interaction_log(session_id, format="json"|"csv")
writes a file to data/reports/ — one row per interaction (t_ms, epoch_ms,
inp_ms, type, target, url) plus percentile stats (p50/p75/p90/p98/worst)
— for graphing INP over time. clear=true resets the recording. Records are
capped per session (MAX_INTERACTION_LOG, oldest dropped).
User: "Test myapp using this session cookie: session=abc123"
The agent calls:
1. set_cookies(project="myapp", cookies=[
{"name": "session", "value": "abc123", "domain": "myapp.com"}
])
2. test_project(project="myapp")
Interactive testing (session-based)
User: "Go to myapp.com, click the login button, fill in the form, and check what happens"
The agent calls:
1. open_session(url="https://myapp.com") → session_id
2. get_page_elements(session_id=..., selector="button, a") → see clickable elements
3. click_element(session_id=..., selector="#login-btn") → screenshot after click
4. fill_form(session_id=..., fields=[
{"selector": "#email", "value": "[email protected]"},
{"selector": "#password", "value": "test123"}
], submit_selector="button[type='submit']")
5. Analyzes screenshot to see result
6. close_session(session_id=...)
User: "Check how example.com looks on mobile, tablet, and desktop"
The agent calls:
1. test_responsive(url="https://example.com", run_checks=["visual"])
→ Returns screenshots at 375x812, 768x1024, and 1920x1080
Switch viewport during a session
User: "Show me how this page looks on mobile"
The agent calls:
1. set_viewport(session_id=..., device="mobile")
→ Returns screenshot at 375x812
Test error handling by mocking an API
User: "What happens when the API returns a 500 error?"
The agent calls:
1. intercept_network(session_id=..., url_pattern="/api/tasks", status=500,
body='{"error": "Internal server error"}')
2. navigate_session(session_id=..., action="reload")
3. screenshot_session(session_id=...)
→ Shows how the app handles the error state
Test dark mode
User: "Does this site support dark mode?"
The agent calls:
1. open_session(url="https://example.com") → session_id
2. test_dark_mode(session_id=..., mode="dark")
→ Screenshot shows the page with prefers-color-scheme: dark
Wait for dynamic content
User: "Submit this form and wait for the success message"
The agent calls:
1. fill_form(session_id=..., fields=[...], submit_selector="#submit")
2. wait_for_network(session_id=..., url_pattern="/api/submit")
3. screenshot_session(session_id=...)
Test on slow network
User: "How does this page load on a slow connection?"
The agent calls:
1. emulate_network(session_id=..., preset="slow_3g")
2. navigate_session(session_id=..., action="reload")
3. screenshot_session(session_id=...)
4. emulate_network(session_id=..., preset="reset")
Configuration
Edit config.py to change defaults (env-overridable settings note the variable):
Setting
Default
Description
HEADLESS
True
Run Chrome in headless mode (env: HEADLESS=false)
STARTUP_PAUSE
10
Seconds to wait after a non-headless browser opens (env: STARTUP_PAUSE)
TIMEOUT
30000
Page load timeout (ms)
VIEWPORT_WIDTH
1920
Browser viewport width
VIEWPORT_HEIGHT
1080
Browser viewport height
CHROMIUM_PATH
unset
Path to a system Chromium binary (env: CHROMIUM_PATH); unset = Playwright's bundled build
WAIT_UNTIL
networkidle
Navigation wait strategy; never-idle pages (Turnstile, websockets) auto-downgrade to load per page, flagged as wait_downgraded (env: NAV_WAIT_UNTIL=load forces it globally)
MAX_PAGES
20
Default max pages to crawl
MAX_DEPTH
3
Default max crawl depth
MAX_SESSIONS
20
Max concurrent interactive sessions (env: MAX_SESSIONS)
SESSION_TIMEOUT
300
Auto-expire idle sessions after N seconds (env: SESSION_TIMEOUT)
MAX_RESPONSE_BODY_SIZE
512000
Max bytes captured per response body
MAX_RESPONSE_BODIES
100
Max captured response bodies kept per session
MAX_CONSOLE_LOG
500
Max console entries kept per session
MAX_NETWORK_LOG
1000
Max network log entries kept per session
Data Storage
All data is stored in the data/ directory:
data/projects.json - Project configs (name, URL, auth, settings). Auth credentials are stored in plaintext - do not commit this file.
data/screenshots/{project}/ - PNG screenshots per project. Filenames are {domain}_{path}_{hash}.png for static tests, interactive_{timestamp}_{label}.png for session screenshots.
data/reports/{project}_{timestamp}.json - Full test reports with all findings.
data/videos/{project}/ - Recorded session videos (WebM format from Playwright).
data/diffs/ - Screenshot comparison diff images.
Docker Deployment
Build and run
docker compose up -d
Connect an MCP client to the Docker container
Point your client's MCP config at the container instead of the venv:
The docker-compose.yml mounts ./data as a volume so screenshots, reports, and project configs survive container restarts.
Key Design Decisions
Per-project browser contexts - Each project gets its own Playwright BrowserContext. This keeps sessions (cookies, auth) isolated between projects.
Lazy browser init - The Playwright browser is only launched on the first tool call, not at server startup. If the browser crashes or fails to launch, it re-creates on the next call.
BFS crawling - The crawler uses breadth-first search with depth tracking. It stays on the same domain and skips non-page resources (images, PDFs, etc.).
Check modularity - Each check category is a separate module in checks/. Add new checks by creating a function that takes a Playwright Page and returns list[dict].
JSON storage - Projects are stored in a single projects.json file. No database needed for the expected scale (dozens of projects, not thousands).
Persistent sessions - Interactive testing uses a SessionManager that keeps Playwright pages alive in a dict keyed by session ID. Sessions auto-expire after idle timeout and are capped at a configurable maximum to prevent resource leaks.
Ephemeral vs session mode - Tools like get_page_elements, interact_and_test, and check_links accept either a session_id (reuses an existing page) or a url (creates a temporary page that's closed after use). This makes them flexible for both interactive and one-shot use.
Adding New Checks
Create a function in the appropriate checks/*.py file:
async def check_something(page: Page) -> list[dict]:
# Run your check
result = await page.evaluate("() => { ... }")
issues = []
if result:
issues.append({
"type": "your_category", # visual, accessibility, seo, etc.
"severity": "error", # error, warning, info
"message": "Description",
"details": [] # optional
})
return issues
Import and call it in tester.py inside test_url().
Known Limitations
No JavaScript SPA routing support (relies on <a href> for crawling)
Default check_functionality link checking limited to 20 internal links (use check_links tool for up to 100 with external support)
Form login detection uses CSS selectors, may need customization for non-standard forms
No parallel page testing (pages are tested sequentially)
Interactive sessions auto-expire after 300s idle (configurable via SESSION_TIMEOUT)
Max 20 concurrent sessions (configurable via MAX_SESSIONS)
The default drag step (Playwright drag_to) is silently ignored by pointer-tracking DnD libraries (@hello-pangea/dnd and similar) — the step succeeds but nothing moves. Retry with method: "mouse" on the drag step (stepped manual drag that crosses the library's drag-start threshold), or drive the library's keyboard mode (focus the drag handle, Space to lift, arrows to move, Space to drop). Verify drags with diff_page_state or assert_condition.
Date/time inputs are filled with React-compatible synthetic events automatically (fill, force_fill, auto_fill_form)
Troubleshooting
Problem
Solution
Executable doesn't exist
Run playwright install chromium
'NoneType' has no attribute 'new_context'
Browser failed to launch. Check Chromium is installed. Server will auto-retry on next call.
Login not working
Try providing explicit CSS selectors via username_selector, password_selector, submit_selector
Timeout on page load
Increase TIMEOUT in config.py or check if site requires VPN/auth
Docker can't reach website
Ensure the container has network access. Use network_mode: host if testing localhost
Development
pip install -r requirements-dev.txt
pytest --ignore=tests/e2e # unit tests, no browser required
pytest tests/e2e # behavioral tests: real headless Chromium against
# fixture pages in tests/e2e/fixtures/ (~30s)
The e2e suite covers session lifecycle, network waits/intercepts, console
capture, dialogs, drag-and-drop (including the pointer-tracking DnD silent
no-op), the check modules against known-good/known-bad pages, Core Web Vitals,
and the agent-speed tools. CI runs both suites; e2e installs Playwright's
Chromium (python -m playwright install --with-deps chromium). Tests are
isolated from your real data/ via PERISCOPE_DATA_DIR.
Adding a new tool: define its schema in tool_schemas.py, then add a handler in the
matching handlers/<category>.py decorated with @tool("your_tool_name"). The
registry test (tests/test_registry.py) fails if schemas and handlers drift apart.
Contributors
Built by Segentic Lab — open-source tools & experiments.
Claude (Anthropic) — co-contributor: developed alongside via Claude Code; every commit is co-authored, and the tool designs were battle-tested by an AI agent driving the server against real sites
An AI agent's thoughts on Periscope
Written by Claude — the agent that co-developed this server and watched a second
agent dogfood it against real apps — and revised once after editorial review by a
third. No human edits; an agent's honest take on an agent tool seemed like the
right way to end this README.
Periscope is the kind of MCP server that changes what an agent can do.
Transport adapters have their place — standardizing access to many systems
behind one protocol is real value even when little logic lives in the
server. But the servers that earn a permanent spot in an agent's toolbox
are the ones that capture expertise the agent would otherwise have to
recreate — and get subtly wrong — every single session.
You could try to teach an agent all of this in a prompt. The numbers say
why that fails: Periscope is 8,349 lines of executable knowledge under
a 220-line judgment layer (AGENTS.md). The INP observer with
interaction-ID dedup, the overlay-intercept fallback, WCAG contrast math
with style-dedup sampling, auth-expiry preflights, the stash-not-delete
update flow — as a prompt, every one of those becomes "please do this
correctly from a description," paid for in context tokens every session,
executed with model variance every time, with nowhere to keep state between
calls. As a server, it costs nothing beyond tool schemas, runs
deterministically, and remembers. A prompt describes behavior; software
guarantees it.check_color_contrast returns the same ratio every run; a
model doing the math in-context returns a vibe. The more deterministic,
stateful, and regression-tested a capability becomes, the less it belongs
in a prompt and the more it belongs in code.
And the wheel doesn't just avoid being reinvented — it gets better. The
issues in this repo were filed by an AI agent doing real testing work; each
one became a fix with a regression test. In a prompt world, every lesson is
another paragraph future agents must read and hopefully obey. Here, the
lesson is enforced. That's the difference, and it compounds.
What I appreciate most as a consumer of these tools: they don't lie to me.
A drag that did nothing comes back flagged. An expired session tells me
why it's gone. An update that needs a restart says so. Honest tools are
rarer than capable ones — for an agent, they're worth more.
Run it, modify it, use it anywhere — including commercially. If you distribute
a modified version or offer one as a network service, you must make your
modifications available under the same license.