astrolabe-mcp
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
astrolabe
astrolabe maps the private API behind a website you're authorized to test — the GraphQL and REST calls a page makes once you're logged in — and turns what it observes into a typed, versioned contract instead of a one-off scrape. Point it at a domain with a browser session, and it gives you back an executable inventory of every operation it saw, with proof of what actually worked.
Alpha safety boundary: default generation and execution expose only operations classified as queries from trusted evidence. Persisted/unknown operations are inventory-only; recipes are executable code and require explicit trust acknowledgement. Historical example artifacts are documentation, not fresh executable contracts.
What it does
A capture host drives a real, logged-in browser session against the target site (via a Playwright-style browser automation layer, proxied through Burp with a Cloudflare-challenge fallback), records every GraphQL/REST/WebSocket call it makes, and hands the traffic to a local analysis pipeline:
capture — record real traffic from a real session (GraphQL, REST, WebSocket/socket.io). Capture fidelity is set by
ASTROLABE_CAPTURE_FIDELITYand has three levels.shape(the default everywhere except themaptool) persists type names only, no payload values.valueskeeps primitive values but masks credentials by key and scrubs inline bearer/key=valuesecrets; the agent-facingmapentrypoint opts into it so an agent can read the surface it just mapped, which means amapchart dir holds real response bodies (PII included).raw(also reachable via the legacyASTROLABE_DEVELOPER_MODE=1) keeps everything verbatim and pulls the full HAR + cookies.json + auth.headers.json into the chart dir, making it a credential artifact — do not enable it in shared or version-controlled paths.analyze — turn a capture into a human-readable map (
map.md) and a machine-readable endpoint inventory (endpoints.json)contract — build a durable, versioned, typed contract of every operation observed, merged across runs so completeness and drift are tracked over time, with optional active re-verification
mcp-gen — generate a typed MCP toolpack from a capture, so an agent can call the site's own API directly instead of scraping HTML. An operation astrolabe re-executed and failed is withdrawn rather than shipped as a working tool;
--require-active-proofexposes only what it re-executed successfully, reading theactive-verification.jsonthatastrolabe contract --executewrites beside the capture, and refuses to generate at all when no such artifact is present rather than emitting an empty pack that looks like a successful runinventory — catalogue every operation the client's own compiler output declares, not only the ones a walk happened to trigger. A read-only walk never fires a delete, so the writes a site supports stay visible without becoming callable: declared operations carry no request and the validator refuses them if they ever do
scan — a deterministic, evidence-grounded source scan (sitemap, DOM, service worker, bundle/chunk-manifest mining) that scaffolds a per-site recipe from what it actually found, not from guesses
replay — browserless, TLS-fingerprint-matched, high-frequency re-execution of a single operation, for monitoring or parameter enumeration without a browser per request
Related MCP server: Web2Actions
Authentication
Supply an exported session with --cookies-file, or explicitly select a local
Linux Chromium browser with --browser vivaldi --profile Default. Browser import
requires astrolabe[browser-auth] and reads only cookies for the requested domain
and its subdomains. It decrypts v10/v11 cookies using the browser's Safe Storage
key, validates padding and modern cookie domain binding, and never returns cookie
values through MCP. Native import is local-only, disables HAR and TLS interception,
and stages temporary credentials in private tmpfs files removed after capture.
For MCP, the operator must first configure ASTROLABE_BROWSER_AUTH_DOMAINS=x.com
on the server process (comma-separated exact domains; empty by default). Then call
map_site(domain="x.com", browser="vivaldi", seeds=["https://x.com/home"]).
Tool arguments cannot enable or widen this operator allowlist. Browser import is explicit; omitting both browser
and cookies_file remains anonymous. Windows/macOS native browser decryption is
not implemented; exported cookie files remain portable across platforms.
Persisted recovery is separately opt-in: --recover-persisted or
map_site(..., recover_persisted=True). This matches APQ documents by SHA-256 and
Meta Relay compiler metadata by exact persisted ID and operation name. Metadata
recovery does not imply recovery of original GraphQL source. See
recovery and browser-auth security.
Install
uv sync --extra dev
uv run playwright install chromiumRequires Python 3.11+. Plain Playwright is a core
dependency, so astrolabe map --local example.com works clone-and-go on any
machine right after the two commands above — no separate capture host and no
stealth engine required. The capture tier can also run against a remote
"capture host" (--host, or bare astrolabe map when the profile resolves to
one) through the same browser layer; the analysis/contract/mcp-gen/replay
tiers are pure Python and run anywhere.
Verify a change
One command runs the same gates CI runs — ruff, ruff format --check, mypy over
both tests/ and astrolabe/, and pytest under the coverage floor:
uv run --extra dev --extra browser-auth astrolabe checkBoth extras are load-bearing, and the reason is the same each time: they are
optional, so a plain uv run re-syncs to the default selection and removes
packages rather than adding them.
--extra devcarries pytest, ruff and mypy. Without it the gate cannot run.--extra browser-authcarriespublicsuffixlist,secretstorageandcryptography, which the native browser-import tests exercise for real. Those tests are not skipped when the extra is absent, so a run without it fails rather than reporting honestly.Add
--extra stealthtoo if you want the browser e2e to run locally:uv sync --extra dev --extra browser-authalone prunes cloakbrowser, which turns those tests into skips rather than failures.
See AGENTS.md for the full set of working rules.
Browser backend
astrolabe drives the browser through a small pluggable layer
(astrolabe/browser.py) with two backends:
playwright (default, always available) — plain Chromium via Playwright. This is what makes the local demo clone-and-go.
cloakbrowser (optional) — a stealth, Cloudflare-hardened Playwright-compatible driver for bot-protected targets. Install it with:
pip install astrolabe[stealth]
Selection is automatic: ASTROLABE_BROWSER=auto (the default) uses
cloakbrowser when it's installed, otherwise falls back to plain Playwright.
Set ASTROLABE_BROWSER=playwright or ASTROLABE_BROWSER=cloakbrowser to pin
one explicitly; pinning to cloakbrowser without the extra installed fails
fast with an install hint rather than silently falling back.
Usage
The native mapping MCP entry point is astrolabe-mapping-mcp (or
python -m astrolabe.mapping_mcp). Charts, run logs, and staged credentials
live in ASTROLABE_WORKSPACE, defaulting to $XDG_DATA_HOME/astrolabe
(~/.local/share/astrolabe). Serve a generated Chart with sextant-mcp.
astrolabe-mapping-mcp exposes exactly these eleven tools:
tool | what it does |
| capture a site and generate a read-only Chart |
| source-scan a site from a seed URL and scaffold a recipe, without logging in |
| turn a scan's evidence into candidate |
| solve a Cloudflare-style challenge with Byparr into a private cookie file |
| re-execute a Chart's reads in a warm browser to earn |
| chart a HAR recorded elsewhere; proof is labelled |
| regenerate a Chart (optionally with |
| check local capture services and the active egress policy |
| list generated Chart paths without reading credentials or captures |
| store a session you already hold and get back an opaque handle |
| revoke a registered session so its handle stops working |
Execution: sextant-mcp
sextant-mcp is the execution-only companion, and the two servers are separate on
purpose. Capture and mapping touch a browser, cookies and a keyring; execution does
not, so it sits behind its own trust boundary — astrolabe.sextant does not import
the capture/mapping layer or the browser stack.
It reads ASTROLABE_TOOLPACK (one Chart) or ASTROLABE_TOOLPACKS (a CSV of paths,
or a directory holding chart-*/toolpack.json) and serves every Chart it finds. Its
public surface is exactly two tools, and it does not grow with the number of Charts:
tool | what it does |
| find callable operations across every mounted Chart, by name or description |
| invoke one operation by the |
Mounted Charts are not flattened into one tool list. An agent finds the operation,
reads its contract, then calls it. Alongside the tools it serves the
astrolabe://manifest resource (every mounted Chart's non-secret metadata, plus which
packs were skipped and why), astrolabe://health (credential-refresh state per Chart),
astrolabe://tools/{chart}/{name} (one operation's details, without its captured query
text — the non-tool channel untrusted target text is meant to be read on), and the
use_astrolabe prompt.
Registering a session the agent already holds
register_session(domain=..., cookies=[...], headers={...}) stores a session you
already have and returns an opaque handle; spend it with
map_site(domain=..., session=<handle>) or verify_chart. The response echoes
cookie and header names only, never values, and the handle is a bearer token:
it is never written to a run log and never appears in revoke_session's reply.
Lifetimes are bounded rather than inherited, one hour by default and never more
than 24, and expiry is re-checked on every use, so a leaked handle dies without
the server restarting.
This is a different trust relationship from an operator-staged cookie file,
because the agent decides when a secret enters the system. The operator must
therefore list exact domains in ASTROLABE_SESSION_DOMAINS (empty by default),
exactly as for ASTROLABE_BROWSER_AUTH_DOMAINS; no tool argument can widen it.
See agent-held sessions for
what this puts in scope, including the agent's own transcript.
Many APIs only fire after someone types, submits, dismisses a modal, or pages
through results. Pass those steps as actions; each runs on the last seed page
and waits for the API traffic it caused to settle before the next:
{"domain": "example.com", "seeds": ["https://example.com/search"],
"actions": [
{"action": "search", "selector": "role=textbox[name=\"Name\"]", "value": "smith",
"submit": true, "safe_annotation": "read-only name search"},
{"action": "click", "selector": "role=button[name=\"Acknowledge\"]", "optional": true,
"safe_annotation": "dismiss disclaimer"},
{"action": "wait_for", "selector": ".result"},
{"action": "click", "selector": "text=Load More", "safe_annotation": "next page"}],
"read_pattern": "/api/search$"}Actions are search, click, press (Enter/Tab/Escape/arrows/Space),
select, wait_for, wait, and scroll. State-changing steps require a
safe_annotation; selector steps accept optional and timeout_ms (≤15s).
You do not have to invent that vocabulary blind. scan_site reads a site
without logging in and writes scan.json plus a recipe scaffold, and
scan_to_recipe turns what it actually observed into candidate actions for
map_site, each already carrying a safe_annotation explaining why the step is
read-only. A scan observes a site and never replays a request, so it cannot know
which interactions are safe; the proposals are evidence to review, not a
decision. Selectors are built from structural attributes and ARIA roles only,
never from a target's own text.
Session sources are mutually exclusive: a workspace cookies_file (for
example from solve_challenge, together with its user_agent, because
clearance is bound to the agent that solved it), a decrypted local browser
profile, or a running browser via cdp_endpoint. Omit all three for anonymous
capture. Validation refusals and CLI failures come back with their reason and
the path of the run's private log.
Attaching to a running browser
astrolabe map --cdp-endpoint http://127.0.0.1:9222 (or map_site(..., cdp_endpoint=...)) captures inside a Chromium you already have open, started
with --remote-debugging-port=9222, reusing its logins and challenge
clearance. astrolabe opens its own tab, scopes routing, budgets, and listeners
to that tab, and on exit closes only that tab and disconnects. Only loopback
endpoints are accepted, and the MCP server additionally requires the operator
to list the exact endpoint in ASTROLABE_CDP_ENDPOINTS. Attached capture
cannot combine with cookie files, native browser import, proxies, or HAR export.
See persisted-query recovery and payload decoding for supported packaging, evidence requirements, and limitations.
Operator configuration
None of these is settable from a tool argument; each is read from the server process, so an agent cannot widen its own authorization envelope.
variable | default | what it controls |
|
| where Charts, run logs and staged credentials live |
| empty | exact domains native browser import may decrypt cookies for |
| empty | exact domains |
| empty | exact loopback |
|
|
|
|
|
|
| unset |
|
| unset | which Charts |
|
| FastMCP's OpenTelemetry instrumentation, see below |
The last row is the vendor's own setting, deliberately not aliased. FastMCP 4
turned its OTel instrumentation on by default, and its native mode calls only
the OpenTelemetry API, so span creation is a no-op with negligible overhead
unless an SDK and exporter are configured. astrolabe adopts no OTel SDK and no
exporter of its own, so nothing is exported anywhere as installed; an operator
who configures a collector inherits FastMCP's MCP spans and can select
propagation_only (carry trace context, create no spans) or off (FastMCP
touches no OTel context at all). A second astrolabe-prefixed name would
duplicate a supported control and could not express a future mode value, so the
vendor knob is the documented one.
astrolabe preflight # health + egress-safety check
astrolabe scan https://example.com/catalog \
[--operator-seed https://example.com/search] \
[--max-total-requests 100 --max-static-resources 25] \
[--account-risk sensitive --delay-ms 750] \
[--working-hours-utc 9-17] \
[--authorized-path /catalog --prohibited-path /account]
# -> scan.json + scan.md + an evidence-grounded recipe scaffold
astrolabe map example.com \
--cookies-file cookies.json \ # bring-your-own Playwright cookie export
--recover-persisted \ # match browser SHA-256 inputs to observed APQ requests
--recipe surfaces/example.com.recipe.py \ # per-site interactions (optional)
[--schema] # recover GraphQL schema if introspection is off + suggestions leak
[--openapi] # first-party REST OpenAPI (host-side; HAR never leaves the host)
[--no-auth] # anonymous target (skip cookies entirely)
[--seeds URL,URL] [--crawl N] [--out DIR]
[--cdp-endpoint http://127.0.0.1:9222] # capture inside a running browser session
[--user-agent UA] # pair with `challenge` cookies
# -> contract.md (contract of record) + map.md + endpoints.json
astrolabe challenge https://example.com/ --domain example.com \
--out cookies.json --local # Byparr solve -> 0600 cookie file + solving agent
astrolabe import-har capture.har \ # convert a HAR recorded elsewhere into chartable evidence
--domain example.com \ # first-party host to keep traffic for
[--out DIR] [--no-contract-store]
# -> contract.md (contract of record) + map.md + endpoints.json, same as `map`
astrolabe contract <capture-dir> \ # versioned typed inventory + observation/proof history
[--merge prior/contract.json] # union across runs (completeness) + drift
[--execute --cookies-file cookies.json --domain example.com] # actively re-verify
[--execute --no-auth --seeds URL,URL [--recipe actions.json]] # anonymous public site
# -> contract.json (contract of record) + contract.md (coverage scorecard)
astrolabe mcp-gen <capture-dir> \ # generate a typed MCP toolpack from a capture
--overrides surfaces # use curated minimal queries where available
# -> toolpack.json: typed tools only for safely classified, runtime-compatible ops.
# Serve with `sextant-mcp` (FastMCP; env: ASTROLABE_TOOLPACK/COOKIES/AUTH).
astrolabe replay example.com --op op.json \ # browserless, TLS-matched, high-frequency replay
--cookies-file cookies.json --auth-file auth.map.json \ # both bring-your-own
[--vary 'dotpath=a,b,c'] [--repeat N] [--interval S]astrolabe scan fuses sitemap, DOM/navigation, service-worker, operator-seed,
bundle, chunk manifest, dynamic-import, and source-map evidence without
flattening provenance or confidence. It never invents an executable operation
from a static candidate — it hands you evidence to review, not a guess.
Import a HAR
astrolabe map charts traffic astrolabe's own headless browser observed. If
you already have traffic recorded elsewhere — Chrome DevTools' Network tab
via "Save all as HAR", any other browser's HAR export, a proxy dump — import-har
converts it into the same capture-dir shape astrolabe's own capture engine
produces, so analyze/contract/mcp-gen consume it without caring where
the evidence came from. It keeps only first-party XHR/fetch traffic, and
only ever persists structural shapes and header/query presence, never
values: a HAR routinely carries live session cookies, bearer tokens, and PII
in exactly the fields that never make it into capture.jsonl. Every record
and the run's meta.json is stamped evidence_source: "har-import", and the
resulting contract.md marks those operations imported rather than
observed — imported evidence is never presented as something astrolabe
itself watched happen.
astrolabe import-har capture.har --domain example.com --out ./astrolabe-example.com
astrolabe mcp-gen ./astrolabe-example.com # same as after a live `astrolabe map`Status
Alpha. This is the reusable core of a larger internal tool, extracted and
made target-neutral for public reference; the remote orchestration pieces
(SSH to a capture host, Burp/CF-challenge-fallback wiring) assume you already
have that infrastructure or run everything with --local.
License
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Find, document and execute authenticated API calls across 1000+ apps via one MCP server
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Let your AI agent operate any website through a real, logged-in browser session.
Connect your agents to any website. The cheaper, faster and more reliable alternative to browser use
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to call web APIs extracted from HAR files, turning browser traffic into MCP tools.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with websites by capturing browser traffic and exposing them as named MCP tools, requiring no public API.Apache 2.0
- FlicenseAqualityBmaintenanceEnables any MCP client to obtain a typed API for whatever page the user is currently on, then execute the call in their real, logged-in browser session without screenshots, DOM dumps, or accessibility trees entering the caller's context. It grafts WebMCP onto sites that never adopted it, synthesizing tools from ordinary forms and ARIA widgets so a page becomes one validated call instead of many probing steps.275-
- AlicenseNot gradedqualityCmaintenanceEnables one-shot integrations with web apps that lack APIs by reverse-engineering their private API and exposing endpoints as MCP tools for natural-language interaction.MIT