periscope-mcp
Periscope MCP is a 66-tool, Playwright-powered MCP server for AI agents to test, audit, and interact with websites and web apps.
Project Management
Create, list, retrieve, and delete testing projects with configurable base URLs, crawl depth, and page limits.
Authentication
Form-based login, HTTP Basic Auth, cookie injection, programmatic login execution, interactive login for 2FA/SSO/CAPTCHA, and copying auth between projects.
Static & Automated Testing
Test a single URL with visual, accessibility, functionality, SEO, performance, and GEO checks.
Crawl entire sites (BFS, same-domain) and run full project audits with saved JSON reports.
Test responsive layouts across mobile, tablet, and desktop viewports.
Persistent Browser Sessions
Open, close, and list long-lived browser sessions; set viewport via device presets or custom dimensions.
Interactive Actions
25 action types: click, fill, type, select, navigate, hover, press key, check/uncheck, scroll, evaluate JS, drag, right-click, upload file, wait for network, and more.
Page Analysis
Form validation analysis, link checking, interaction timing, table parsing, toast capture, keyboard navigation audits, color contrast checks, and raw HTML extraction.
Debugging & Diagnostics
Console errors, network request/response logs, API response bodies, localStorage/sessionStorage read-write, cookie access, and computed CSS styles.
Advanced Testing
Mock/clear network requests, switch into iframes, emulate slow/offline network conditions, toggle dark mode, handle JS dialogs, upload files, and wait for elements to disappear.
Assertions & Smart Tools
Programmatic pass/fail assertions (text_contains, element_exists, url_contains, etc.), smart element finder by text/role/proximity, auto-fill entire forms with inferred test data, and named page-state snapshots (save, restore, diff).
Performance & Core Web Vitals
Capture FCP, LCP, CLS, TBT, INP, and resource metrics; export INP time series with percentile stats; run full Google Lighthouse audits.
Accessibility & SEO/GEO Audits
Alt text, ARIA, heading hierarchy, color contrast, keyboard nav; meta tags, Open Graph, JSON-LD, canonical URLs, robots.txt; AI-crawler access (GPTBot, ClaudeBot), llms.txt, and WebMCP compliance.
Recording
Record browser workflows as WebM video files.
Web Utilities
Search DuckDuckGo, fetch any URL as readable text or raw HTML, and retrieve a structured catalog of all 66 tools with workflow examples (
describe_tools).
Runs Google Lighthouse audits to evaluate web page performance, accessibility, and SEO, returning structured scores.
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_conditionreturnspassed: true/falsewith the actual value; checks return structured issues.One call instead of ten —
auto_fill_formdetects, infers, and fills a whole form;interact_and_testbatches 25 action types with checks;test_projectcrawls 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 |
|
Filling a form | One call per field, agent invents test data |
|
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 |
|
Diagnosing a broken page | Ask for logs, replay requests | Response bodies, console, and network are captured automatically; mock APIs with |
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.
Related MCP server: Scout
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.shFully unattended (no confirmation prompts):
git clone https://github.com/segentic-lab/periscope-mcp.git && cd periscope-mcp && ./install.sh -yAlready 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 (setsCHROMIUM_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.shPulls 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 withgit 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 chromiumInstallation (Docker)
docker compose up -dSee 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.jsonand adjust paths), or runclaude mcp add periscope -- /path/to/venv/bin/python /path/to/server.pyCursor / Windsurf — add the block above to
~/.cursor/mcp.json/~/.codeium/windsurf/mcp_config.jsonCodex CLI — add to
~/.codex/config.toml:[mcp_servers.periscope]withcommandandargsas aboveCustom 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 atskills/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/periscopeA 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.mdcontains 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 a new testing project |
|
| List all projects | (none) |
| Get project details |
|
| Delete project + data |
|
Authentication (7 tools)
Tool | Description | Required Params |
| Configure username/password form login |
|
| Configure HTTP Basic Auth |
|
| Inject session cookies |
|
| Execute login using configured auth |
|
| Open a visible window to log in by hand (2FA/SSO/CAPTCHA), then |
|
| Capture the manual-login session; the project then runs authenticated + headless |
|
| Copy auth config + session state between projects |
|
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 a single URL (screenshot + checks) |
|
| Discover all pages from base URL |
|
| Full audit: crawl + test all pages |
|
Results (4 tools)
Tool | Description | Required Params |
| Get screenshot file path |
|
| List saved test reports | (optional: |
| Read a report file |
|
| HTML+PDF dossier of every tool call this run — args (redacted), verdicts, timings, screenshots | (none) |
Session Management (5 tools)
Sessions keep browser pages alive across tool calls, enabling multi-step interactive workflows.
Tool | Description | Required Params |
| Open persistent browser session ( |
|
| Close session and free resources |
|
| List all active sessions | (none) |
| Switch viewport size (8 device presets or custom w/h) |
|
| Adopt a popup/new tab (OAuth, target=_blank) as a new drivable session |
|
set_viewport presets: mobile_sm (320x568), mobile (375x812), mobile_lg (428x926), tablet (768x1024), tablet_lg (1024x1366), laptop (1366x768), desktop (1920x1080), desktop_lg (2560x1440)
Interactive Actions (7 tools)
Tool | Description | Required Params |
| Click element ( |
|
| Fill form fields, optionally submit |
|
| Native |
|
| Multi-step workflow with 25 actions (see below) |
|
| List matching elements with attributes |
|
| Save / run / list / delete named step sequences (reusable workflows) | (varies by action) |
| Scroll element into viewport without clicking |
|
interact_and_test supports 25 step actions:
click, force_click, fill, force_fill, type, select, select_option, wait, wait_for, wait_for_text, screenshot, navigate, hover, press_key, check, uncheck, scroll_to, scroll_within, evaluate_js, drag, right_click, go_back, go_forward, upload_file, wait_for_network
Analysis (10 tools)
Tool | Description | Required Params |
| Analyze form validation messages | (url or session_id) |
| Pixel diff between two screenshots |
|
| Named visual-regression baselines: set once, check for a hard pass/fail |
|
| Test at mobile/tablet/desktop viewports |
|
| Comprehensive link checker (internal + external) | (url or session_id) |
| Measure click-to-result timing |
|
| Parse HTML table into structured JSON (headers → cell values) |
|
| Capture visible toast/notification messages |
|
| Real Google Lighthouse audit: 0-100 scores, Core Web Vitals, failed audits (needs Node.js) |
|
| Export real INP time series (per interaction) as JSON/CSV + percentile stats |
|
Workflow Speed (8 tools)
Tool | Description | Required Params |
| Quick screenshot of current page state |
|
| Run checks on active session (no new page) |
|
| Browser history: back, forward, or reload |
|
| Accept/dismiss JS alert/confirm/prompt (call BEFORE trigger) |
|
| Set file(s) on |
|
| Wait for specific API URL pattern to complete |
|
| Wait for element to disappear (modal close, spinner gone) |
|
| Raw outerHTML of elements, or full page HTML |
|
Advanced Testing (9 tools)
Tool | Description | Required Params |
| Mock API responses (test error/empty/loading states) |
|
| Remove network mocks (all, or by pattern) |
|
| Read localStorage or sessionStorage |
|
| Write to localStorage or sessionStorage |
|
| Switch into iframe content (returns new session) |
|
| Get actual rendered CSS values |
|
| Throttle network: |
|
| Toggle |
|
| Click a trigger and capture the downloaded file (path, sha256, text preview) |
|
Recording & Console (3 tools)
Tool | Description | Required Params |
| Record workflow as video |
|
| Tab-order and focus indicator audit | (url or session_id) |
| Get all console errors/logs (passive monitoring) |
|
AI Agent Speed Tools (10 tools)
Tool | Description | Required Params |
| Programmatic pass/fail: text_contains, element_exists, url_contains, etc. |
|
| Batch assertions — every verdict in one call, no early abort |
|
| Semantic page map: roles, names, states + ready selectors in one call |
|
| Smart finder by text, tag, role, or proximity to another element |
|
| Auto-detect fields, infer types, fill with test data. One call = many fills. |
|
| All captured network requests (URL, status, method, type) |
|
| Actual API response body text (diagnose 400/500 errors) |
|
| Named checkpoints: snapshot / restore / diff page state |
|
| Read all cookies from session |
|
| WCAG AA/AAA contrast ratio checks on text elements |
|
Web, Discovery & System (4 tools)
Tool | Description | Required Params |
| Search DuckDuckGo: titles + URLs + snippets |
|
| Fetch URL → readable Markdown (or text/html); |
|
| Structured catalog of all tools with workflows and tips | (none) |
| Install status + update check/apply + fetch current AGENTS.md | (none) |
Test Checks
Visual (checks/visual.py)
Broken images (incomplete load or 0 natural width)
Missing favicon
Horizontal overflow / layout issues
Very small text (< 12px)
Missing body background color
Images without explicit width/height dimensions
Accessibility (checks/accessibility.py)
Images missing
alttext (decorative images exempt:alt="",role="presentation"/"none",aria-hidden)Links and buttons without accessible names (checks text,
aria-label, resolvablearia-labelledby,title,img[alt], svg<title>;aria-hiddenelements exempt)Form inputs without associated labels (
label[for], wrapping label,aria-label/aria-labelledby,title)Heading hierarchy (missing H1, multiple H1, skipped levels)
Missing
langattribute on<html>Duplicate
idvalues (breaklabel[for]and aria references)ARIA validity: unknown
rolevalues,aria-labelledby/describedby/controls/owns/activedescendantreferences to non-existent idsMissing skip navigation link (scans the first 5 links)
Elements with
tabindex > 0Keyboard navigation audit (tab order, visible focus indicators, element-identity cycle detection) — via
test_keyboard_navigationtool
Functionality (checks/functionality.py)
Broken internal links (HTTP HEAD check, up to 20 links in
check_functionality)Comprehensive link checker with external link support (up to 100 links) — via
check_linkstoolForms without action or submit button
Orphan buttons outside forms
External links missing
target="_blank"Required form field count
Autocomplete disabled inputs
SEO (checks/functionality.py -> check_seo)
Page title: missing, too long (> 60 chars), or very short (< 15 chars)
Meta description: missing, too long (> 160 chars), or very short (< 50 chars)
Missing viewport meta tag
Missing canonical URL
H1 heading: missing or more than one
Open Graph: missing entirely, incomplete core tags (
og:title/description/image/url), non-absoluteog:image, missingtwitter:cardJSON-LD structured data: missing or unparseable blocks
noindexvia robots meta orX-Robots-Tagresponse headerrobots.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 undersite_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.txtpresence 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 exposesdocument.modelContext— registered tool enumeration with schema/name/description validationJSON-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.
Performance (checks/functionality.py -> get_performance_metrics)
DOM content loaded time (ms)
Full page load time (ms)
First paint / first contentful paint (ms)
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).
Test Output Format
Each test_url call returns:
{
"url": "https://example.com",
"status": "success",
"status_code": 200,
"title": "Page Title",
"screenshot_path": "/path/to/screenshot.png",
"load_time_ms": 1500,
"issues": [
{
"type": "accessibility",
"severity": "error",
"message": "3 images missing alt text",
"details": ["img1.png", "img2.png", "img3.png"]
}
],
"issue_count": 5,
"issues_by_severity": {"error": 1, "warning": 2, "info": 2},
"issues_by_type": {"accessibility": 2, "seo": 2, "visual": 1},
"performance": {
"dom_content_loaded_ms": 120,
"load_complete_ms": 1500,
"first_paint_ms": 140,
"first_contentful_paint_ms": 140,
"resource_count": 25,
"total_size_bytes": 512000,
"total_size_kb": 500
},
"console_errors": []
}test_project returns an aggregated report with per-page results + summary.
Usage Examples
Basic test (no auth)
User: "Test https://example.com for issues"
The agent calls:
1. create_project(name="example", base_url="https://example.com")
2. test_project(project="example")
3. Analyzes results and reports findingsTest with login
User: "Test https://myapp.com, login is admin/password123"
The agent calls:
1. create_project(name="myapp", base_url="https://myapp.com")
2. set_form_login(project="myapp", login_url="https://myapp.com/login",
username="admin", password="password123")
3. login_project(project="myapp")
4. test_project(project="myapp")Test with Basic Auth
User: "Test https://staging.example.com, it uses basic auth admin/secret"
The agent calls:
1. create_project(name="staging", base_url="https://staging.example.com")
2. set_basic_auth(project="staging", username="admin", password="secret")
3. login_project(project="staging")
4. test_project(project="staging")Test with cookies
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": "user@test.com"},
{"selector": "#password", "value": "test123"}
], submit_selector="button[type='submit']")
5. Analyzes screenshot to see result
6. close_session(session_id=...)Scripted multi-step workflow (no session needed)
User: "Test the checkout flow on myshop.com"
The agent calls:
1. interact_and_test(
url="https://myshop.com/products/1",
steps=[
{"action": "click", "selector": "#add-to-cart"},
{"action": "wait", "timeout": 1000},
{"action": "click", "selector": "#checkout-btn"},
{"action": "fill", "selector": "#email", "value": "test@test.com"},
{"action": "screenshot", "label": "checkout_form"},
{"action": "click", "selector": "#submit-order"}
],
run_checks=["visual", "accessibility"]
)Responsive testing
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 1920x1080Switch 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 375x812Test 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 stateTest 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: darkWait 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 |
|
| Run Chrome in headless mode (env: |
|
| Seconds to wait after a non-headless browser opens (env: |
|
| Page load timeout (ms) |
|
| Browser viewport width |
|
| Browser viewport height |
| unset | Path to a system Chromium binary (env: |
|
| Navigation wait strategy; never-idle pages (Turnstile, websockets) auto-downgrade to |
|
| Default max pages to crawl |
|
| Default max crawl depth |
|
| Max concurrent interactive sessions (env: |
|
| Auto-expire idle sessions after N seconds (env: |
|
| Max bytes captured per response body |
|
| Max captured response bodies kept per session |
|
| Max console entries kept per session |
|
| 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}.pngfor static tests,interactive_{timestamp}_{label}.pngfor 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 -dConnect an MCP client to the Docker container
Point your client's MCP config at the container instead of the venv:
{
"mcpServers": {
"periscope": {
"command": "docker",
"args": ["exec", "-i", "periscope", "python", "/app/server.py"]
}
}
}Persist data
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 PlaywrightPageand returnslist[dict].JSON storage - Projects are stored in a single
projects.jsonfile. No database needed for the expected scale (dozens of projects, not thousands).Persistent sessions - Interactive testing uses a
SessionManagerthat 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, andcheck_linksaccept either asession_id(reuses an existing page) or aurl(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/*.pyfile:
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 issuesImport and call it in
tester.pyinsidetest_url().
Known Limitations
No JavaScript SPA routing support (relies on
<a href>for crawling)Default
check_functionalitylink checking limited to 20 internal links (usecheck_linkstool 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
dragstep (Playwrightdrag_to) is silently ignored by pointer-tracking DnD libraries (@hello-pangea/dndand similar) — the step succeeds but nothing moves. Retry withmethod: "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 withdiff_page_stateorassert_condition.Date/time inputs are filled with React-compatible synthetic events automatically (
fill,force_fill,auto_fill_form)
Troubleshooting
Problem | Solution |
| Run |
| Browser failed to launch. Check Chromium is installed. Server will auto-retry on next call. |
Login not working | Try providing explicit CSS selectors via |
Timeout on page load | Increase |
Docker can't reach website | Ensure the container has network access. Use |
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.
Sebastijan Bandur (@segentic-lab) — author & maintainer
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_contrastreturns 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.
License
GNU AGPL-3.0 — see LICENSE.
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.
Available Tools
74 toolsassert_allA
Batch assertions: evaluate MANY conditions in one call and get every verdict — no early abort, so the response is the complete pass/fail picture (overall passed, failed_count, per-assertion results with actual values). Each item takes the same fields as assert_condition. Prefer this over sequential assert_condition calls when verifying a state with 2+ expectations.
Inputs: assertions (required), session_id (required).
assert_conditionA
Assert a condition on the current page and get a hard pass/fail plus the actual value — no screenshot to interpret. Supports text_contains, text_equals, element_exists, element_visible, element_count, url_contains, title_contains, attribute_equals. Returns {passed, actual, expected}. The verification primitive — prefer it over screenshot-squinting.
Inputs: assertion (required), session_id (required), expected, selector, +1 more.
auto_fill_formA
Detect a form's fields, infer each type (email/phone/name/address/date…), fill realistic test data, and optionally submit — one call replacing 5-10. Returns which fields were filled and with what. Use overrides={selector: value} for specific values and submit=true to submit.
Inputs: session_id (required), submit, overrides, form_selector.
check_color_contrastA
Check WCAG color contrast ratios for text elements on the page. Samples one element per unique text style (color/background/size), so repeated nav items don't exhaust the budget — 'checked' counts style groups, 'elements_represented' the elements they cover. Reports failures against AA or AAA thresholds.
Inputs: session_id (required), level, selector, max_results.
check_linksA
Crawl all links on a page and report each one's URL, status code, and OK/broken result — catching 404s and dead anchors. External links are skipped unless check_external=true. Returns the per-link results plus a broken-link summary. Works on a session or a URL.
Inputs: url, project, max_links, session_id, +1 more.
clear_interceptsA
Remove network mocks created by intercept_network — all of them, or only those registered with a given URL pattern. Returns {success}. Use to restore real backend responses after testing mocked states.
Inputs: session_id (required), url_pattern.
click_elementA
Click an element in a session page. Returns a screenshot and the new URL/title after click. If a full-screen portal overlay (Radix/shadcn dialogs & menus) intercepts the pointer, automatically falls back to an element-level JS click and flags click_method='js_dispatch' — no workaround needed. Use force=true to bypass actionability checks for other cases (hidden/animating elements).
Inputs: selector (required), session_id (required), force, observe.
close_sessionA
Close a browser session and free its resources (page, context, captured logs). Returns {success}. Call it when finished; using a closed or expired id returns a 'session not found' error that explains why (idle-expired, evicted, or crashed).
Inputs: session_id (required).
compare_screenshotsA
Pixel-diff two screenshot files. Returns the percentage of differing pixels and writes a diff image highlighting the changed regions (path in the result). Use for visual-regression checks — capture with test_url/screenshot_session, then compare. threshold sets per-channel color tolerance.
Inputs: screenshot1 (required), screenshot2 (required), threshold.
copy_authA
Copy auth configuration and, when possible, the live login session (cookies + localStorage via storage_state) from one project to another on the same domain. Returns {success, session_copied}; session_copied is false when only the config/cookies could transfer. Use to reuse a login across related projects.
Inputs: to_project (required), from_project (required).
crawl_projectA
Discover a project's pages by breadth-first crawling internal links from its base URL, bounded by max_pages/max_depth (overridable per call). Discovery is deterministic (links sorted before the cap) and sitemap-seeded when a sitemap.xml/robots.txt Sitemap is present, so the same site yields the same page subset every run. Returns the discovered URLs plus pages_not_crawled[] (≤100, else a count) so a hit cap is never silent. Runs in the project's authenticated context. Set meta=true to also get each page's title + meta description (captured during the crawl, so behind-login/JS pages work), and save_md=true to save every crawled page as readable Markdown to data/fetches// (returns pages[] with saved_path + saved_dir). Discovery (optionally + capture) — use test_project to crawl and run full audits.
Inputs: project (required), meta, save_md, save_dir, +3 more.
create_projectA
Create a persistent testing project: a named website/web-app target with its base URL and crawl limits, saved to disk and reused by crawl_project, test_project, and authenticated sessions. Returns the stored project config. Create this first, then attach auth (set_form_login / set_basic_auth / set_cookies) and run tests.
Inputs: name (required), base_url (required), max_depth, max_pages, +1 more.
delete_projectA
Permanently delete a project and its saved configuration and auth. Returns {success}. Irreversible; afterwards the name is free to reuse. Does not remove screenshots/reports already written to disk.
Inputs: name (required).
describe_toolsA
Return a structured catalog of Periscope's tools grouped by category, with parameters, workflow examples, and tips — optionally filtered to one category. Returns the guide as structured JSON. Call this first if you're new to the server, to plan a testing workflow.
Inputs: category.
download_fileA
Click a trigger and capture the file it downloads — the honest way to verify exports (CSV, PDF, invoices). The download waiter is armed BEFORE the click so fast downloads aren't missed, and the click uses the same overlay-fallback as click_element (export buttons inside Radix menus work). Returns the saved path, size, sha256, source URL, and for small text files a text_head preview so content can be asserted without another call. Files land in data/downloads/.
Inputs: selector (required), session_id (required), timeout.
emulate_networkA
Throttle a session's network to a preset — slow_3g, fast_3g, offline, or reset. Returns {success}. Persists across navigations until reset. Use to test loading spinners, skeleton states, offline fallbacks, and timeout handling.
Inputs: preset (required), session_id (required).
fill_formB
Fill form fields in a session page and optionally submit. Use force=true to bypass actionability checks when overlays or dialogs block the inputs.
Inputs: fields (required), session_id (required), force, observe, +1 more.
find_elementA
Find elements by text content, tag, ARIA role, and/or proximity to another element, ranked by match quality. Returns {found, elements} with the best CSS selector for each. Use it to get a reliable selector from what you can see (e.g. a button's text) instead of guessing.
Inputs: session_id (required), tag, near, role, +2 more.
flowA
Save and re-run named step sequences — define a workflow once (login, checkout, smoke path), replay it in any session. action='save' stores steps (interact_and_test's exact format, all 25 actions); action='run' executes a saved flow on a session via the same engine as interact_and_test; action='list' shows saved flows; action='delete' removes one. Deliberately minimal: verify outcomes by following a run with assert_all or visual_check. Flows persist in data/flows/ across sessions and server restarts.
Inputs: name, steps, action, session_id, +2 more.
get_computed_styleA
Read the actual rendered CSS values (after stylesheets and inheritance) for the requested properties on matching elements. Returns per-element property→value maps. Use to verify colors, fonts, spacing, display, or opacity programmatically instead of eyeballing a screenshot.
Inputs: selector (required), properties (required), session_id (required), max_results.
get_console_errorsA
Return browser console output (errors, warnings, logs) captured passively on a session since it opened or since the last read; clears the buffer by default. Returns the buffered entries. First stop when debugging a broken page — no steps required.
Inputs: session_id (required), clear.
get_cookiesA
Read all cookies from a session's browser context (optionally filtered by domain). Returns {cookies, total} with each cookie's name/value/domain/path/flags. Essential for debugging auth/session issues — confirm the expected session cookie is present and scoped correctly.
Inputs: session_id (required), domain_filter.
get_interaction_logA
Export the real INP (Interaction to Next Paint) time series for a session — one record per interaction Periscope drove (click/typing), each with its input-to-next-paint latency, event type, target, timestamp, and URL. Saves a JSON (for graphing) or CSV file and returns percentile stats (p50/p75/p90/p98/worst). Use after driving interactions (interact_and_test, click_element, fill_form…) — ideal for a long interactive test where you want to see all INP times, not just the worst. Unlike Lighthouse (which can't measure INP in lab mode and falls back to TBT), this is measured from actual Event Timing entries.
Inputs: session_id (required), clear, format.
get_local_storageA
Read a session page's localStorage (or sessionStorage) — all entries, or specific keys. Returns the key/value pairs as an object. Use to inspect client-side state (tokens, flags, cached data) when debugging.
Inputs: session_id (required), keys, storage.
get_network_logA
Return the network requests captured on a session — each with URL, HTTP method, status, resource type, and size. Optionally filter by URL substring; clear=true empties the log after reading. Returns the request list. Use to see which API calls fired and their status when debugging.
Inputs: session_id (required), clear, url_filter.
get_page_elementsA
List elements matching a CSS selector with their attributes (tag, text, id, class, href, value, visible, enabled, aria_label, role). Pass 'attributes' for extra HTML attributes (data-, aria-, style, ...) and 'full_text' for complete text content instead of the 80-char preview. Works on a session or a URL. Standard CSS selectors only — Playwright-specific pseudo-classes (:has-text, :visible) are not supported here.
Inputs: selector (required), url, project, full_text, +3 more.
get_page_htmlA
Return the raw outerHTML of matching elements, or the full page HTML if no selector, truncated to max_length. Returns the HTML string(s). Use to inspect component/markup structure — e.g. head meta tags for SEO, or a widget's DOM. Standard CSS selectors only.
Inputs: session_id (required), selector, max_length.
get_page_mapA
Semantic page map in ONE call: every interactive element (links, buttons, inputs, custom controls) plus landmarks and headings, in document order — each with its ARIA role, accessible name, live state (disabled/checked/expanded/value), and a ready-to-use CSS selector. The fastest way to answer 'what can I do on this page?' — use it to orient before clicking instead of multiple get_page_elements calls. Interactive elements with no accessible name are flagged unnamed (an accessibility finding in itself). Output is compact: only truthy state fields, capped at max_nodes with an explicit truncated flag.
Inputs: session_id (required), max_nodes, include_hidden.
get_projectA
Get one project's saved configuration: base URL, max_pages/max_depth, screenshot directory, and which auth (form/basic/cookies) is set up. Returns {success, project}. Use it to confirm setup before crawling, testing, or logging in.
Inputs: name (required).
get_reportA
Load a saved test report by file path and return its full contents — per-page issues, site-wide findings, and run metadata. Returns {success, report}. Get valid paths from list_reports.
Inputs: report_path (required).
get_response_bodyA
Return the captured response body text for a request whose URL contains a substring (optionally filtered by method). Matching is a plain substring test against the full URL incl. query string — not a regex or glob. On a miss it lists the captured candidate URLs so you can adjust the pattern in one round-trip. Bodies are captured automatically for fetch/xhr/document requests, making this the fastest way to diagnose a 400/500 — no setup before the request.
Inputs: session_id (required), url_pattern (required), method.
get_screenshotA
Get the saved screenshot file path for a URL previously tested in a project. Returns {success, url, screenshot_path}. Locates the PNG on disk after test_url/test_project — it does not capture a new image (use screenshot_session for that).
Inputs: url (required), project (required).
get_table_dataA
Parse an HTML table into structured data, mapping header cells to each row's values. Returns {headers, rows, total_rows} where rows are header→value objects. Use instead of scraping table markup by hand when verifying tabular content.
Inputs: session_id (required), max_rows, selector.
get_toast_messagesA
Capture currently-visible toast/notification/alert text on a session — checks common patterns ([role=alert], [role=status], [aria-live], .toast, .notification, Toastify, Sonner, Radix) or your own selector. Returns the messages found. Set wait_ms to let a toast animate in first. Use to verify success/error notifications after an action.
Inputs: session_id (required), wait_ms, selector.
handle_dialogA
Arm a one-shot handler for the NEXT JavaScript dialog (alert/confirm/prompt) on a session — accept or dismiss, with optional prompt text. Returns {success}. Must be called BEFORE the action that triggers the dialog, otherwise the dialog blocks the page and times out.
Inputs: action (required), session_id (required), prompt_text.
interact_and_testB
Execute a multi-step interaction workflow. Supports 25 actions: click, force_click, fill, force_fill, type, select, select_option, wait, wait_for, wait_for_text, screenshot, navigate, hover, press_key, check, uncheck, scroll_to, scroll_within, evaluate_js, drag, right_click, go_back, go_forward, upload_file, wait_for_network. Can work on an existing session or create an ephemeral page.
Inputs: steps (required), url, project, run_checks, +4 more.
interactive_loginA
Open a VISIBLE browser window for a human to log in by hand — the way to authenticate flows that can't be automated (2FA/MFA, SSO/OAuth redirects, CAPTCHA, magic links, device confirmation). After you finish logging in, call save_login to capture the session; future headless sessions on the project reuse it. Requires a display on the server (DISPLAY set).
Inputs: project (required), login_url.
intercept_networkA
Mock matching API responses on a session — return a custom status/body/content-type for requests whose URL contains a substring. Returns {success}. Use it to force error, empty, or loading states without a real backend; call BEFORE the triggering action, and clear_intercepts to remove. once=true intercepts only the first match.
Inputs: session_id (required), url_pattern (required), body, once, +3 more.
list_projectsA
List all saved testing projects with their base URL, crawl limits, and configured auth type. Returns an array of project configs (empty if none exist). Use it to discover the project names the other project/auth/testing tools expect.
Inputs: no named parameters.
list_reportsA
List saved test reports (the JSON files test_project writes), for one project or all projects. Returns each report's path and timestamp, newest first. Pass a path to get_report to read one.
Inputs: project.
list_sessionsA
List active browser sessions with their session_id, current URL, and idle time. Returns an array (empty if none open). Use it to recover a session id or spot sessions nearing the idle-timeout or the concurrency cap.
Inputs: no named parameters.
login_projectA
Execute a project's configured login — submit the form, apply Basic Auth, or inject cookies — and persist the resulting authenticated session (storage_state) for reuse. Requires set_form_login / set_basic_auth / set_cookies first. Returns {success} with login details. Re-run it when auth expires mid-test.
Inputs: project (required).
measure_interactionA
Click an element and measure how long until the result settles. Returns elapsed_ms, a 'measures' note stating exactly what was timed, and the click's real interaction_to_next_paint_ms when measurable. Three modes: wait_for_network (URL substring) measures until that response completes — use this for buttons whose handler fires a request asynchronously, where plain network-idle settles early and under-measures; wait_for (selector) measures until it appears; default measures to the first network-idle window.
Inputs: selector (required), session_id (required), wait_for, wait_for_network.
open_sessionA
Open a persistent browser session and return {session_id, url, title, screenshot}. The page stays alive across tool calls so you can explore, click, fill, debug, and accumulate console/network logs — the main workflow for anything multi-step. Pass project to share its authenticated context; headed=true opens a visible window. Sessions expire after idle timeout, so close_session when done.
Inputs: url (required), headed, project.
page_stateA
Named page-state checkpoints. action=snapshot saves URL + cookies + storage + DOM signature under a name; action=restore navigates back to it and restores cookies/storage; action=diff compares the current DOM against the snapshot (added/removed/changed elements + tag count changes). Enables testing multiple paths from the same starting point.
Inputs: name (required), action (required), session_id (required).
periscope_systemA
Install status, self-update, and the current agent guide — Periscope's self-maintenance tool. action='status' (read-only): running version vs on-disk version, git commit, install type, capabilities (Node/Lighthouse, display for headed, Chromium), active session count, and whether an update is available. action='agents_md' (read-only): returns the CURRENT AGENTS.md so you can refresh a stale pasted copy of your operating guide. action='update': dry-run by default (commits behind + incoming changes); apply=true runs the updater (git pull + deps, data/ untouched) — new code loads only after the MCP server restarts, and the response says so explicitly. Managed installs (Docker, no .git) refuse update with guidance.
Inputs: apply, force, action.
record_sessionA
Run a sequence of steps while recording a video of the browser (Playwright video capture). Returns the saved .webm file path. Steps use the same format as interact_and_test. Use it to produce a visual artifact or repro of a workflow; for assertions/checks use interact_and_test instead.
Inputs: url (required), steps (required), project.
run_checks_on_sessionA
Run the audit checks (visual/accessibility/functionality/seo/performance/geo) against a session's CURRENT page — after your interactions, without opening a new page (unlike test_url). Returns the same {issues[], per-check results} structure as test_url. Use to audit a state you reached by clicking/filling.
Inputs: session_id (required), checks.
run_lighthouseA
Run a real Google Lighthouse audit against a URL. Returns 0-100 category scores, Core Web Vitals lab metrics (LCP, TBT, CLS, Speed Index), and the failed audits, and saves the full JSON report. Requires Node.js — finds it on PATH or auto-detects nvm installs (~/.nvm); if none exists, returns the exact nvm install commands. Launches its own headless Chrome: no session or project auth state applies.
Inputs: url (required), device, timeout, categories.
save_loginA
Capture the authenticated session (cookies + localStorage) from an in-progress interactive_login, save it to the project, and close the visible window. The project then opens authenticated sessions headlessly. Re-run interactive_login when the session expires.
Inputs: project (required).
screenshot_sessionA
Screenshot the session's current page as-is — no actions performed. Returns the image path (full-page by default; full_page=false captures just the viewport). Full-page captures are PREPARED for fidelity: sticky/fixed headers are neutralized (no mid-page duplication), animations disabled, reduced-motion emulated, and scroll-reveal sections forced visible — the applied steps are reported in capture_prep. Pass raw=true to capture the unprepared stitch. Use to grab state at a point in a workflow; interactive tools already return screenshots, so don't call this after every step.
Inputs: session_id (required), raw, selector, full_page.
scroll_into_viewA
Scroll an element into the viewport without clicking it. Returns {success}. Use to trigger lazy-loaded content/images or to bring a section into view before screenshotting.
Inputs: selector (required), session_id (required), observe.
select_iframeA
Switch into an iframe and return a NEW session id scoped to that frame's content — use it like a normal session for elements inside the iframe, and keep the parent id for page-level actions. Close the returned session when done. Needed because cross-frame content isn't reachable through the parent session's selectors.
Inputs: selector (required), session_id (required).
select_optionA
Select an option from a native or a custom dropdown (Radix/shadcn combobox), auto-detecting which. Choose by value, label, or index. Returns {success} and the resulting selection. For custom dropdowns it opens the menu and clicks the matching option — use this rather than click+click. When a page has several attribute-less elements, pass element_index to target the Nth match of the selector (Playwright '>>' syntax is not supported).
Inputs: selector (required), session_id (required), index, label, +3 more.
select_pageA
Adopt a popup or new tab this session opened (window.open, target=_blank, OAuth/payment windows) as a NEW session id you can drive with every normal tool — clicks, assertions, logs. Console/network recording attaches the instant the driver sees the popup open, so early traffic is captured (requests firing in the popup's first milliseconds can precede any driver's visibility — a browser-automation limit, not a periscope one). Returns {session_id, url, title}; with several popups open, call without index to list them first. The parent session keeps working for the original tab.
Inputs: session_id (required), index.
session_reportA
Generate a human-readable dossier of EVERYTHING done this server run — every tool call in chronological order with arguments (secrets redacted), pass/fail verdicts, timings, error messages, and embedded screenshot thumbnails — as a self-contained HTML file plus a PDF. Made for handing to your user to review the whole session; add your findings via 'notes' so the report opens with your summary. The journal records automatically from server start; clear=true resets it after reporting (e.g. between test rounds).
Inputs: pdf, clear, notes, title, +1 more.
set_basic_authA
Configure HTTP Basic Auth credentials for a project — the browser sends them on every request in that project's context. Stored, not executed: call login_project to apply, then pass project to your sessions. Returns {success}. Use for browser Basic-Auth prompts, not HTML login forms (use set_form_login for those).
Inputs: project (required), password (required), username (required).
set_cookiesA
Seed a project with session cookies to skip an interactive login (e.g. cookies copied from a logged-in browser). Each cookie needs name+value+domain (path defaults to '/'). Stored, not executed: call login_project to inject them. Returns {success}.
Inputs: cookies (required), project (required).
set_form_loginA
Configure username/password form login for a project (stored, not executed yet). For standard HTML login forms; field/submit selectors are auto-detected but can be overridden. Returns {success}. Call login_project afterwards to actually log in. For 2FA/SSO/CAPTCHA use interactive_login instead.
Inputs: project (required), password (required), username (required), login_url (required), +3 more.
set_local_storageA
Write key/value entries to a session page's localStorage (or sessionStorage), optionally clearing existing entries first. Returns {success}. Use to seed client state (feature flags, tokens, cached data) to reproduce a specific app state; reload if the app reads storage only at load time.
Inputs: entries (required), session_id (required), storage, clear_first.
set_viewportA
Resize a session's viewport to a device preset or custom width/height, then screenshot. Returns the new size and screenshot. Persists for later actions in the session — use this to test responsive layouts inside an ongoing session (unlike test_responsive, which opens throwaway pages).
Inputs: session_id (required), width, device, height, +1 more.
test_dark_modeA
Emulate prefers-color-scheme (dark or light) on a session and screenshot the result. Returns the screenshot. Use to verify a site's dark/light theming without touching OS settings; the emulation persists for later actions in the session.
Inputs: mode (required), session_id (required).
test_form_validationA
Audit a page's form validation: locate forms, list their required fields, and collect messages from :invalid fields and custom error elements. Returns the per-form field/validation details. Use to verify client-side validation behaves as intended. Works on a session or a URL.
Inputs: url, project, session_id, form_selector.
test_projectA
Full-site audit: crawl every page (up to max_pages) and run the selected checks on each, saving a timestamped JSON report. The crawl is deterministic + sitemap-seeded, so consecutive runs cover the same pages and before/after comparisons are reliable (issue #22). Returns per-page issues, site-wide findings (e.g. duplicate titles/descriptions), an auth_check, pages_not_tested[] when the cap is hit, and a coverage delta (pages_added/pages_dropped) vs the previous report. Pages that bounce to the login page come back as auth_lost, never as fake success. Reload the saved report with get_report.
Inputs: project (required), checks, max_pages, use_sitemap.
test_responsiveA
Load a URL at several viewport sizes (default mobile 375x812, tablet 768x1024, desktop 1920x1080) and screenshot each, optionally running checks per size. Returns each viewport's screenshot path and any issues. Catches layout breakage across breakpoints in one call. Pass custom viewports as [{name,width,height}].
Inputs: url (required), project, viewports, run_checks.
test_urlA
Screenshot and audit a single URL in one shot (opens then closes a throwaway page). Runs the selected checks — visual, accessibility, functionality, seo, performance, geo — and returns {status, title, screenshot path, issues[]} where each issue has type/severity/message; never-idle pages come back flagged (wait_downgraded), not as errors. Pass project for authenticated pages. For multi-step flows or repeated checks on one page, use a session instead.
Inputs: url (required), checks, project.
upload_fileA
Set file(s) on an element by path, without the OS file picker. Returns {success}. Provide absolute paths that exist on the server. For a picker opened by a button, target the underlying file input's selector.
Inputs: files (required), selector (required), session_id (required).
visual_checkA
Named visual-regression baselines — no screenshot-path bookkeeping. action='set' captures the session page (or one element via selector) as the baseline for 'name'; action='check' captures again and returns a hard verdict: passed (diff_percentage vs max_diff_percent, default 0.5%), plus a diff image with changed pixels highlighted. Baselines are stored per project+name. If a check fails on an intended change, re-baseline with action='set'. Prefer selector-scoped baselines for components — full pages flake more (animations, dynamic content).
Inputs: name (required), session_id (required), action, selector, +3 more.
wait_for_goneA
Block until an element disappears — removed from the DOM or hidden — up to timeout. Returns {success} once it's gone, or times out. Use to wait for a modal/dialog to close or a loading spinner to vanish before the next step.
Inputs: selector (required), session_id (required), timeout.
wait_for_networkA
Block until a network request whose URL contains the given substring completes (optionally filtered by HTTP method), up to timeout. url_pattern is required and is a plain substring match against the full URL including query string — not a regex or glob. Returns the matched request's URL/status/method, or times out. To catch a request fired by a click, run the click and this as consecutive steps in one interact_and_test call; after the fact, read get_response_body/get_network_log instead.
Inputs: session_id (required), url_pattern (required), method, timeout.
web_fetchA
Fetch a URL and return clean, readable content — Markdown by default (structure preserved: headings, lists, links, code, tables), with page boilerplate (nav/footer/cookie bars) stripped via readability extraction. Far fewer tokens than a raw text dump. format='text' for plain text, 'html' for raw HTML (raw_html=true is an alias). Static HTTP fetch by default; render=true loads the page in headless Chromium so client-rendered/SPA content is captured (runs all JS, then extracts) — pass project to render a page behind that project's login (host fetch tools can't). contains=[words] only returns the content if the page contains the term(s) (contains_mode any|all), else omits it to save tokens. save=true (or save_path) writes the full content to disk and returns saved_path. TLS verified by default (verify_ssl=false for dev certs).
Inputs: url (required), save, format, render, +8 more.
web_searchA
Search DuckDuckGo and return result titles, URLs, and snippets (up to max_results). Use to look up documentation, verify external facts, or research during a testing workflow.
Inputs: query (required), max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 74 tools
Descriptions are often precise, but the set contains several overlapping primitives: wait_for_network and upload_file exist both as standalone tools and as interact_and_test actions, while get_page_map/get_page_elements/find_element and test_url/run_checks_on_session cover adjacent ground. An agent could easily select the wrong tool without very careful reading.
Most tools follow a readable verb_noun convention (get_, set_, test_, list_, create_, delete_), but there are conspicuous outliers like interactive_login, visual_check, session_report, page_state, flow, and periscope_system that break the pattern. The naming is understandable overall, but not consistent enough to reliably predict a tool's name from its function.
74 tools is an extreme mismatch for a coherent MCP surface and imposes a heavy selection burden on agents. Even for a broad browser-testing domain, many of these tools are granular variations (assert_condition vs assert_all, compare_screenshots vs visual_check) that could be consolidated into a much smaller, more approachable set.
Coverage is remarkably thorough: project lifecycle, auth setup, crawling, sessions, interactions, assertions, network interception, visual regression, accessibility, and reporting are all present. Minor gaps exist, such as no update_project for changing crawl limits or base URL, no baseline listing/removal for visual_check, and no report deletion, but agents can work around these.
Maintenance
Related MCP Connectors
Screenshot, diff, audit and sitemap-capture any web page — 5 MCP tools for AI agents.
19 free website QA and AI-visibility tools. Remote HTTP MCP, no account, no API key.
Website checker for AI coding agents. Measures your site in a real browser, with evidence.
Website QA for your coding agent: audit SEO, performance, security, accessibility over MCP.
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP server that enables AI agents to perform comprehensive web audits using Google Lighthouse with 13+ tools for performance, accessibility, SEO, and security analysis.111,975 npm75MIT
- AlicenseNot gradedqualityBmaintenancesingle-binary MCP server that gives AI agents a browser. 66 tools for navigation, form filling, data extraction, screenshots, and DOM diffing — built on pure Chrome DevTools Protocol.14MIT
- AlicenseAqualityCmaintenanceMCP server for browser automation that lets LLMs interact with web pages through structured accessibility snapshots, bypassing the need for screenshots.2310,815,609 npmApache 2.0
- AlicenseCqualityCmaintenanceAn MCP server that enables AI agents to autonomously test, debug, and analyze web interfaces visually using Playwright, with 30 tools for screenshots, workflows, performance, and visual comparison.3048 npm84ISC