About periscope
periscope is a macOS command-line browser for AI agents, using WebKit and persistent sessions to read, extract, and interact with pages. It also detects CAPTCHA and bot-check pages.
Key features
- 01WebKit-based Safari browsing
- 02Persistent named sessions
- 03Markdown page reading
- 04JSON record extraction
- 05Page interaction and screenshots
- 06CAPTCHA and bot-check detection
Use cases
- 01Read articles and posts
- 02Extract product or job listings
- 03Navigate pages and complete forms
- 04Inspect visual page content
MCP support
Exposes browser capabilities to MCP clients through the `periscope mcp` command.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEperiscope
A command-line browser for AI agents on macOS. It runs Safari's engine (WebKit), so websites see a normal Safari, and it keeps sessions open between commands.
periscope navigate https://books.toscrape.com/ --session demo
periscope text --session demo # the page as markdown
periscope extract --session demo # the page's records as JSON
periscope click "text:Next" --session demo
Install
brew install oskar-szulc/tap/periscope
periscope install-skill # adds the agent skill to this project
Without Homebrew: curl -fsSL https://raw.githubusercontent.com/oskar-szulc/periscope/main/install.sh | sh
To build from source instead (Xcode 26): swift build -c release, then copy
.build/release/periscope onto your PATH.
For agents
- Claude Desktop: download
periscope-<version>.mcpbfrom the latest release and open it - Claude Code:
/plugin marketplace add oskar-szulc/periscope, then/plugin install periscope@periscope - Codex, Cursor and others:
npx skills add oskar-szulc/periscope - MCP clients: listed in the MCP Registry as
io.github.oskar-szulc/periscope; the command isperiscope mcp, e.g.claude mcp add periscope -- periscope mcp, or in a JSON config:{"mcpServers": {"periscope": {"command": "periscope", "args": ["mcp"]}}} - Any agent with a shell:
periscope docsprints the full reference
Reading a page
| Command | Returns | Use it to |
|---|---|---|
text | The page's main content as markdown, links included | Read an article or a post |
state | URL, title, headings, the start of the content, and every clickable element with a selector and a number (@3) | Decide what to click or fill next |
extract | JSON: the page's repeated items (cards, results, table rows), its structured data, and the next-page link | Scrape a list of jobs, products or results |
links | Every link on the page as an absolute URL (--match to filter) | Collect URLs to visit next |
screenshot | A PNG of the page as displayed | See the layout, or check visual content |
What else you can do
- Act:
click,fill,type,select,scroll,mouse, targeting CSS or what a person sees (text:Next,label:Email) - Stay logged in: named sessions persist;
loginandshowlet you take over the window - Know when you're blocked: CAPTCHA and bot-check pages exit with code 5
Full reference: PERISCOPE.md. Why and how it was built: Building periscope.
Requirements
- macOS 26 or newer, in a logged-in desktop session with the display on
- Not inside a shell sandbox (periscope exits with a message if it is)
License
MIT. Contributions: see CONTRIBUTING.md. Made by Oskar Szulc.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.