ochi · очі

Eyes on the web for your AI assistant. A tiny MCP server that reads pages through your own Chrome (so Cloudflare & co. see a normal person) and turns them into clean data with small per-site extractor scripts: Greasemonkey-style .js files.

Claude ──MCP/stdio──▶ ochi (Python) ──Playwright/CDP──▶ your Chrome ──HTTPS──▶ site

No Docker, no global Node: Python and dependencies are handled by uv. Works on macOS, Windows and Linux.

Status: a personal project, shared as is. It works for me and is tested on macOS, Windows and Linux, but support is best-effort. Issues and pull requests are welcome, especially fixes for extractors broken by site changes and extractors for new sites: see CONTRIBUTING.md.

Setup (once)

1. uv: see installation.

2. Config folder:

   uvx --from git+https://github.com/jennywassweet/ochi ochi init

   This creates ochi.toml, .env and an extractors/ folder for your own extractors in ~/Library/Application Support/ochi (macOS), %APPDATA%\ochi (Windows) or ~/.config/ochi (Linux), and shows which browser it found.

3. Browser: ochi starts its own Chrome window (separate profile ~/.ochi-profile, debugging port 9222) the first time a tool needs it. It finds Chrome, Chromium, Brave or Edge in the usual places; path, profile, port and autostart can be changed in ochi.toml. Log in there only to sites ochi needs (Discogs, Reddit…). No mail, no banking.

4. Discogs token (optional, for the discogs_* API tools): put it into .env as DISCOGS_TOKEN (get one here).

5. Hook into Claude Desktop: add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

   "ochi": {
     "command": "uvx",
     "args": ["--from", "git+https://github.com/jennywassweet/ochi", "ochi"]
   }

   (inside "mcpServers": { … }, then restart Claude Desktop; if uvx isn't found, use its absolute path from which uvx / where uvx). Other MCP clients take the same command.

6. Try it without MCP (put any Discogs seller name instead of SELLER):

   uvx --from git+https://github.com/jennywassweet/ochi ochi-try "https://www.discogs.com/seller/SELLER/profile?format=Vinyl&ochi_max=20"

From a clone (to hack on ochi): git clone https://github.com/jennywassweet/ochi && cd ochi, then uv run ochi-try <url>, and in the Claude config use "command": "uv", "args": ["--directory", "/absolute/path/to/ochi", "run", "ochi"]. Run from a clone, ochi keeps ochi.toml, .env, snapshots/ and reads extractors/ right in the repo folder.

Related MCP server: Chrome MCP Server

Tools

Configuration

ochi's home folder (see Setup; OCHI_HOME moves it) holds:

• ochi.toml (optional, see ochi.example.toml): [chrome] path, profile, port, autostart, args;

• .env: secrets (DISCOGS_TOKEN);

• extractors/: your own extractors, loaded next to the built-in ones (same @name replaces a built-in one);

• snapshots/: output of snapshot.

Environment variables override the file: OCHI_CONFIG (path to the toml), OCHI_CHROME, OCHI_PROFILE, OCHI_PORT, OCHI_EXTRACTORS (your extractors folder). [urls] controls which sites ochi may open (see Security). ochi reads ochi.toml once at start: restart it after editing.

Built-in extractors

The generic extractor

Pages without a specific extractor go to generic. When a page looks like an article (news, blogs, wikis), Mozilla Readability reduces it to the article, with byline and date ([mode: article]). Other pages (listings, front pages, shops) come back as their main text, one line per block ([mode: page]). Readability is used only when it keeps a real share of the page's main content; add ochi_mode=page or ochi_mode=article to the URL to force a mode.

Writing an extractor

// ==Extractor==
// @name        my-site
// @match       https://example.com/articles/*
// @wait        article            (optional CSS selector to wait for)
// @description one line for list_extractors
// ==/Extractor==

async function extract() {
  // runs INSIDE the page: document, fetch() with the page's cookies, etc.
  return { items: [...] };   // or a string
}

// @require lib/Readability.js in the header loads a library before the code (repeatable). Libraries are looked up next to the extractor, then among the built-in ones in extractors/lib/ (see its README for versions and licenses).

A result {..., items: [...]} is rendered one item per line (cheap for the model). @match is a glob where * matches anything (including /); the longest matching pattern wins, and an extractor matching * is the fallback.

Extractor-specific URL params

discogs-market (seller shops, /shop/list, sellers of a release) takes extra ochi_* params. They are applied by ochi after reading the pages (not sent to Discogs), so they combine with any filter the site itself offers:

Prices are shown as the seller lists them; ochi_max, ochi_max_total, ochi_sort and each item's total (price + shipping to you) use Discogs' conversion to your currency when the seller uses another one. shipping: "?" means Discogs doesn't show shipping to your country for that item (check the seller's terms); free_over is the seller's free-shipping threshold, when they have one. Example: https://www.discogs.com/seller/SELLER/profile?style=Psychedelic+Rock&format=Vinyl&ochi_min_media=VG%2B&ochi_sort=total

Development

uv sync                                  # dev tools included
uv run ruff check .
uv run playwright install chromium       # once; browser tests otherwise use an installed Chrome
uv run pytest

Tests never touch the network: extractors run in headless Chromium against saved pages and JSON in tests/fixtures/. When a site changes its layout, save a new snapshot there (strip anything tied to your account), fix the extractor, adjust the test. CI runs the suite on Linux, macOS and Windows.

Security

ochi gives the model a real, logged-in browser. Keep that in mind:

• Use the separate ochi profile and log in only where you need to.

• fetch/show/snapshot open only http(s) pages, and by default not localhost, *.local or private IP addresses (router, NAS, cloud metadata). [urls] in ochi.toml can allow those, limit ochi to a list of sites (allow = ["*.discogs.com"]) or block some (deny). Names are not resolved, so a public name pointing at a private address is not caught. look reads whatever tab is visible.

• Page content is untrusted text and can contain instructions aimed at the model (prompt injection).

• While the browser runs, its debugging port (9222 on 127.0.0.1) lets any local program control it.

Etiquette

Personal use, a handful of pages per session, pauses between pages. No paywall bypassing, no captcha solving — if a site asks for a human, the human clicks.

Contributing

See CONTRIBUTING.md: how to fix or add an extractor, and what is out of scope.

License

MIT