semaphore

A read-only MCP server that reads login-walled web pages by replaying cookies clipped from your own browser. You log into a site normally; a browser extension sends that site's cookies to a local server; an LLM agent calls read_page over MCP and gets clean markdown back. Credentials never reach the agent — only the server holds the cookies, and it can only read (GET), never submit.

Binds 127.0.0.1:8931. Runs in Docker. Fetches with a plain HTTP GET first and falls back to headless Playwright Firefox only when a page needs JavaScript.

Requirements

• Docker + Docker Compose
• A Firefox-based browser (Firefox / Zen) that can load an unsigned extension
• An MCP client that speaks streamable HTTP (e.g. Claude Code)

1. Run the server

docker compose up -d --build
docker logs semaphore | grep "shared secret"   # copy this value

The shared secret is generated on first boot and printed to the logs. Cookies, the secret, and the Playwright profile live in the semaphore-data Docker volume, so they survive restarts. The secret is the auth token for both endpoints — treat it as a credential.

2. Load the Cookie Clip extension

In Firefox/Zen, open about:debugging#/runtime/this-firefox → Load Temporary Add-on → select extension/manifest.json. (Temporary add-ons unload when the browser restarts. To keep it, package extension/ as an unsigned .xpi — this requires xpinstall.signatures.required = false. See extension/README.md.)

Open the extension popup once and paste the shared secret into it. It is stored in browser.storage.local and reused for every clip.

3. Clip cookies for a site

1. Log into the target site in your browser as normal.
2. Open the Cookie Clip popup. It shows the active tab's registrable domain.
3. Confirm or edit the domain, then click Clip cookies.

This sends the domain's cookies (including HttpOnly) plus your browser's user-agent to POST /api/cookies. Re-clip whenever a session expires.

The domain box defaults to the last two labels of the hostname, which is wrong for multi-part TLDs like example.co.uk — edit it by hand in that case.

4. Register the server with your MCP client

claude mcp add --transport http semaphore http://localhost:8931/mcp \
  --header "X-Semaphore-Secret: <secret>"

Both /mcp and /api/cookies require the X-Semaphore-Secret header.

Tools

read_page({ url, format? })

Fetches url and returns it as text. format:

• auto (default) — detects article vs link-list pages and renders each well (Readability for articles, link-preserving markdown for search/result lists).
• markdown — force pure Readability article extraction.
• aria — accessibility-tree snapshot (Playwright). Use this if auto misclassifies a list page and drops its links.
• html — Readability's cleaned HTML.

On a login wall it returns a structured error instead of page content:

{ "error": "auth_required", "domain": "…", "reason": "no_cookies" | "session_expired", "action": "…" }

no_cookies = nothing clipped for that domain; session_expired = clipped cookies no longer authenticate. Re-clip and retry — do not treat the logged-out page as the answer.

session_status({ domain? })

Reports stored domains, cookie counts, earliest cookie expiry, and stored user-agent. Never returns cookie values. Omit domain for all domains.

Remote access over a tailnet (optional)

Keep the server bound to localhost. On the host running Tailscale, expose only the /mcp path over HTTPS:

tailscale serve --bg --set-path /mcp http://localhost:8931/mcp

(Flag names vary by Tailscale version — check tailscale serve --help.) Then point a remote MCP client at https://<machine>.<tailnet>.ts.net/mcp with the same secret header. /api/cookies stays local, so cookies never leave the host, and all fetches egress from the host's IP. Restrict reach with Tailscale ACLs.

Configuration

• SEMAPHORE_DATA_DIR — data directory (default /data in the container).
• SEMAPHORE_HOST — bind address (default 127.0.0.1). Do not bind 0.0.0.0; use tailscale serve for remote access instead.
• Port is fixed at 8931.
• Rotate the secret by deleting /data/secret and restarting; re-enter it in the extension and MCP client.

Layout (for modifying)

Path	What it does
server/index.ts	HTTP server; /api/cookies + /mcp routing; shared-secret auth
server/mcp.ts	MCP tool definitions (read_page, session_status)
server/fetcher/index.ts	Two-tier fetch (HTTP → Playwright Firefox), SSRF guard, rate limiter, auth_required
server/fetcher/extract.ts	Readability + link-preserving extraction; article-vs-list classifier
server/cookies.ts	Per-domain cookie store (/data/cookies.json)
server/rate-limiter.ts	Per-domain serial queue
extension/	The Cookie Clip WebExtension
SPEC.md	Full design spec and rationale

Local dev without Docker: npm install, then npm run dev (needs Node 22; set SEMAPHORE_DATA_DIR to a writable path). npm run build type-checks.

Limitations

• Cookies are frozen at clip time — there is no server-side session refresh. When a site rotates or expires its session, re-clip.
• Read-only by design: no form submission, clicking, or applying. Discovery works because most search is GET (?keywords=…); the final action stays manual.
• The auto classifier misses list pages whose item URLs have no numeric/hex id (pure slugs) — use format: "aria" for those.
• Self-hosted: no proxy rotation or anti-bot handling. It is meant for reading your own authenticated sessions, from your own IP.
• Automated reading of authenticated content may violate a site's terms. Use it for sessions you are entitled to, and within those terms.