create_projectLABSCO SUMMARY
The tools encode the testing, which is the whole difference.
Raw browser control makes an agent reinvent the QA loop every session: click, screenshot, squint, decide. Here the decision is the return value — assert_condition gives a boolean and the value it read, and silent no-ops such as an ignored drag come back flagged instead of as fake success. test_project is the one to reach for first on an unfamiliar site, because it produces a saved report rather than a transcript. This is not a replacement for a general browsing server; it is what you connect when the job is finding and reporting defects.
What it is
An MCP server that gives an agent a browser shaped for testing. It drives headless Chrome through Playwright, but the tools are higher level than the browser API: assertions return pass or fail with the actual value, a form is filled in one call, and a site-wide crawl plus accessibility, SEO, visual and functionality checks is a single tool.
What you get
- Hard verdicts instead of screenshots to interpret —
assert_conditionreturnspassedwith the value it saw, andassert_allruns a batch without aborting on the first failure - Site-wide work in one call —
test_projectcrawls and audits every page and saves a report;test_urlcovers a single page;crawl_projectjust discovers what exists - Persistent authenticated sessions, including form, basic and cookie auth, and a visible interactive login for 2FA, SSO or CAPTCHA that then continues headless
- Multi-step flows through
interact_and_test, which batches 25 step actions from click and fill through drag, upload and evaluate_js - Form work that does not take a call per field —
auto_fill_formdetects the fields, infers realistic data, and reports per-field failures - Debugging captured without setup —
get_console_errors,get_network_log,get_response_bodyfor the actual API body behind a 500, andintercept_networkto mock a response and test the error state - Real measurements rather than proxies —
run_lighthousefor genuine Lighthouse scores andget_interaction_logfor INP measured from the interactions it drove - Audits a browser binding cannot give you — accessibility, SEO, colour contrast against WCAG, and a GEO check covering robots.txt AI-crawler access, llms.txt, WebMCP annotations and JSON-LD
- State handling for tricky flows —
page_statesnapshots, restores and diffs;select_pageadopts a popup as a drivable session;select_iframesteps inside a frame describe_toolsreturns the whole catalog with workflows and tips, so an agent can orient itself without you pasting documentation
Requirements
Python 3.11 or higher, plus Playwright and Chromium. On Debian or Ubuntu the install script does the whole thing — prerequisites, virtual environment, dependencies, Chromium, a headless self-test — and writes an mcp-config.json with absolute paths for your machine; --system-chromium uses a browser you already have. On other platforms it prints the commands rather than changing anything. A Docker compose setup is included. The client points at venv/bin/python server.py over stdio. run_lighthouse additionally needs Node.js.
Setup effort
Build from source — clone the repository, then follow the steps on this page and add the configuration for your client
USE CASES
Auditing a whole site and getting a report
Crawl it, run the accessibility, SEO, visual and functionality checks, and read the saved report.
Testing a flow behind a login
Log in once — visibly if there is 2FA — then run the multi-step flow headless in a persistent session.
Getting a straight answer about whether something worked
Assert the condition and read the verdict with the actual value, rather than judging a screenshot.
Diagnosing a page that fails intermittently
Read the console, the network log and the actual response body behind the failing request.
Checking how an app behaves when the API fails
Mock the response, then assert what the interface actually did with it.
Measuring performance for real
Run Lighthouse for the scores and export the INP series from the interactions actually driven.
74 tools
Listed in project docs. Your client may show a different list.
list_projectsget_projectdelete_projectset_form_loginset_basic_authset_cookieslogin_projectinteractive_loginsave_logincopy_authtest_urlcrawl_projecttest_projectget_screenshotlist_reportsget_reportsession_reportopen_sessionclose_sessionlist_sessionsset_viewportselect_pageclick_elementfill_formselect_optioninteract_and_testget_page_elementsflowscroll_into_viewtest_form_validationcompare_screenshotsvisual_checktest_responsivecheck_linksmeasure_interactionget_table_dataget_toast_messagesrun_lighthouseget_interaction_logscreenshot_sessionrun_checks_on_sessionnavigate_sessionhandle_dialogupload_filewait_for_networkwait_for_goneget_page_htmlintercept_networkclear_interceptsget_local_storageset_local_storageselect_iframeget_computed_styleemulate_networktest_dark_modedownload_filerecord_sessiontest_keyboard_navigationget_console_errorsassert_conditionassert_allget_page_mapfind_elementauto_fill_formget_network_logget_response_bodypage_stateget_cookiescheck_color_contrastweb_searchweb_fetchdescribe_toolsperiscope_systemBEFORE YOU INSTALL
What to know first
Tools you get
74 tools named in the project's documentation. run_lighthouse needs Node.js and interactive_login needs a display. Step actions such as evaluate_js are arguments of interact_and_test, not tools; describe_tools() lists the catalogue.
Requires
Python 3.11+
Where it runs
All 3 documented clients run the server on your machine.
INSTALLATION
Connect your client
Clone the repository, then follow the steps on this page and add the configuration for your client. This one is built from source rather than installed with a single command.
Server setup
Prerequisites: Python 3.11+ and Playwright + Chromium browser
Debian/Ubuntu quick path: git clone https://github.com/segentic-lab/periscope-mcp.git && cd periscope-mcp && ./install.sh (add -y for fully unattended; --system-chromium to reuse an existing Chrome; --skip-deps to never touch apt/sudo). On other platforms the script does not modify your system — it prints the exact commands (./install.sh --manual macos|fedora|arch|suse|windows)
Manual alternative, in order:
cd periscope-mcp ; python3 -m venv venv ; source venv/bin/activate ; pip install -r requirements.txt ; playwright install chromiumDocker alternative: docker compose up -d, then point the client at the container with command "docker" and args ["exec","-i","periscope","python","/app/server.py"]
Register with your client using the generated mcp-config.json (copy or merge into .mcp.json). Claude Code: cp .mcp.json.example .mcp.json and adjust paths, or claude mcp add periscope -- <YOUR_PATH_TO_VENV>/bin/python <YOUR_PATH_TO_SERVER_PY>. Cursor/Windsurf: ~/.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json. Codex CLI: [mcp_servers.periscope] in ~/.codex/config.toml
Restart your client after configuring
Optional, Claude Code only: install the skill with ln -s "$(pwd)/skills/periscope" ~/.claude/skills/periscope ; for other clients paste AGENTS.md into the system prompt
Updating later: ./update.sh (--force to stash local changes, --full to re-check apt prerequisites)
MCP Clients
Claude Code, Cursor, Windsurf
{
"mcpServers": {
"periscope": {
"command": "<YOUR_PATH_TO_PERISCOPE_MCP>/venv/bin/python",
"args": [
"<YOUR_PATH_TO_PERISCOPE_MCP>/server.py"
]
}
}
}