periscope-mcp
About
Website testing built for AI agents: 63 Playwright tools with hard assertions, auto form-fill, auth sessions, network mocking, and a11y/SEO/GEO + Lighthouse audits.
Details
- Author
- segentic-lab
- Categories
- Developer Tools, Security, Other
Jump to
Setup
Install periscope-mcp in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/segentic-lab/periscope-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
An MCP server that gives AI agents74 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:
Playwright + headless Chrome underneath; site crawling, responsive testing, and screenshot diffing on top. Works withany MCP client— Claude Code, Codex, Cursor, Windsurf, Gemini CLI, custom agents, or anything else that speaks MCP over stdio.
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:
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.
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.
- Python 3.11+
- Playwright + Chromium browser
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.shfrom the repo directory.
The script installs apt prerequisites, creates the venv, installs Python dependencies and Playwright's Chromium, runs a headless self-test, and generatesmcp-config.jsonwith 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|windowsto pick explicitly).
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 regeneratedmcp-config.json. Works on any platform with an existing install. Yourdata/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.
# Clone the repo cd periscope-mcp # Create virtual environment python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt # Install Chromium for Playwright playwright install chromium
Periscope is a standard stdio MCP server: point any MCP client atvenv/bin/python server.pyand you're done../install.shgeneratesmcp-config.jsonwith 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"] } } }
- 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.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]withcommandandargsas above
- Custom agents— any MCP SDK client can spawn the server over stdio with the same command and args
-
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/periscope
A symlink keeps it current with./update.sh(copy the folder instead if you prefer a frozen version).
Any other MCP client: paste the guide.AGENTS.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 viaperiscope_system(action="agents_md")and the complete catalog viadescribe_tools().
Sessions keep browser pages alive across tool calls, enabling multi-step interactive workflows.
set_viewportpresets:mobile_sm(320x568),mobile(375x812),mobile_lg(428x926),tablet(768x1024),tablet_lg(1024x1366),laptop(1366x768),desktop(1920x1080),desktop_lg(2560x1440)
interact_and_testsupports 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
- 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 missingalttext (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)
- Missinglangattribute on<html>
- Duplicateidvalues (breaklabel[for]and aria references)
- ARIA validity: unknownrolevalues,aria-labelledby/describedby/controls/owns/activedescendantreferences to non-existent ids
- Missing skip navigation link (scans the first 5 links)
- Elements withtabindex > 0
- Keyboard navigation audit (tab order, visible focus indicators, element-identity cycle detection) — viatest_keyboard_navigationtool
Functionality (checks/functionality.py)
- Broken internal links (HTTP HEAD check, up to 20 links incheck_functionality)
- Comprehensive link checker with external link support (up to 100 links) — viacheck_linkstool
- Forms without action or submit button
- Orphan buttons outside forms
- External links missingtarget="_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:card
- JSON-LD structured data: missing or unparseable blocks
- noindexvia robots metaorX-Robots-Tagresponse header
- robots.txt blocking search engine crawlers (Googlebot, Bingbot, DuckDuckBot, ...) — error if all are blocked
- Site-wide (viatest_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 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.
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: therealINP, 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 therun_lighthousetool — 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 todata/reports/.
Because Periscope drivesrealinteractions, it can log each one's INP over an extended interactive test.get_interaction_log(session_id, format="json"|"csv")writes a file todata/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=trueresets the recording. Records are capped per session (MAX_INTERACTION_LOG, oldest dropped).
{ "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_projectreturns an aggregated report with per-page results + summary.
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 findings
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")
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")
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"] )
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
User: "Show me how this page looks on mobile" The agent calls: 1. set_viewport(session_id=..., device="mobile") → Returns screenshot at 375x812
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
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
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=...)
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")
Editconfig.pyto change defaults (env-overridable settings note the variable):
All data is stored in thedata/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.
Connect 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"] } } }
Thedocker-compose.ymlmounts./dataas a volume so screenshots, reports, and project configs survive container restarts.
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 inchecks/. Add new checks by creating a function that takes a PlaywrightPageand returnslist[dict].
JSON storage- Projects are stored in a singleprojects.jsonfile. No database needed for the expected scale (dozens of projects, not thousands).
Persistent sessions- Interactive testing uses aSessionManagerthat 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 likeget_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.
- Create a function in the appropriatechecks/*.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 issues
- Import and call it intester.pyinsidetest_url().
- No JavaScript SPA routing support (relies on<a href>for crawling)
- Defaultcheck_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 viaSESSION_TIMEOUT)
- Max 20 concurrent sessions (configurable viaMAX_SESSIONS)
- The defaultdragstep (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)
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 realdata/viaPERISCOPE_DATA_DIR.
Adding a new tool: define its schema intool_schemas.py, then add a handler in the matchinghandlers/<category>.pydecorated with@tool("your_tool_name"). The registry test (tests/test_registry.py) fails if schemas and handlers drift apart.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
