Ghostvault¶
Source-available MCP server for managing browser sessions on any website through AI agents — with anti-detect browser sessions, locked fingerprints, persistent profiles, provider-agnostic login, and anonymous scraping.
What it does¶
Ghostvault lets an AI agent (Claude Desktop, Cursor, ZCode, Cline) drive real browser sessions in an anti-detect Firefox browser — sign in to any website (Google, GitHub, Facebook, your bank, internal apps), switch between accounts, scrape pages, call APIs, and automate any login-gated flow.
Each account gets a locked fingerprint so it always looks like the same device, even across restarts. Sessions, cookies, and fingerprints live on your machine under ~/.ghostvault; nothing is ever sent anywhere.
It also supports anonymous scraping via throwaway sessions (gv_open_ephemeral) — open a URL, extract text/screenshots/links, close. No account, no profile, no login required.
How it works¶
Your AI agent (Claude Desktop / Cursor / Cline)
│ MCP protocol (stdio or HTTP)
▼
┌─────────────────────────────────────────────────┐
│ Ghostvault MCP Server │
│ │
│ 42 tools: │
│ gv_create_account, gv_sign_in, │
│ gv_create_provider, gv_check_session, │
│ gv_detect_login_options, gv_record_login,│
│ gv_open_url, gv_click_element, │
│ gv_api_call, gv_eval_js, ... │
│ │
│ Per-account persistent Camoufox profiles: │
│ profile_A/ ── locked fingerprint A + Google │
│ profile_B/ ── locked fingerprint B + GitHub │
│ profile_C/ ── locked fingerprint C + custom │
│ │
│ Provider recipes: │
│ providers.json (shared login recipes) │
│ google | github | facebook | custom │
└─────────────────────────────────────────────────┘
│ traffic exits via your IP or proxy
▼
Any website (Google, GitHub, your bank, ...)
The agent decides what to do; Ghostvault provides the hands. Each profile is a container — it holds sessions for every website equally, not just one provider. Login is data-driven via provider recipes, so any website's login flow can be described as data, not code.
Why fingerprints are locked (critical)¶
Camoufox generates a fresh random fingerprint on every launch — it does not persist one to the profile directory. Without locking, each launch would look like a brand-new device and anti-bot systems would flag the account.
Ghostvault generates one fingerprint per account at creation, serializes it (BrowserForge fingerprint + noise seeds + OS + device profile) to a sidecar JSON, and passes it back on every launch. Result: an account always presents the same identity.
3 login levels¶
| Level | What it does |
|---|---|
| 1 (manual) | Open login URL → user does everything → detect auth cookies |
| 2 (auto-fill) | Execute provider's login_steps → fill form → click submit |
| 3 (recording) | Record user's login actions → replay automatically next time (pauses for 2FA/captcha) |
Features¶
| Feature | What it means |
|---|---|
| 🎭 Locked fingerprints | Each account always looks like the same device (Camoufox C-level spoofing + 105 config keys + 10 device profiles) |
| 🔌 Provider-agnostic login | Built-in (google, github, facebook) + create custom providers for any website; scan login pages for SSO options |
| 🏗️ 3 login levels | Level 1 (manual), Level 2 (form auto-fill), Level 3 (record user's actions → replay) |
| 🔐 Persistent sessions | Sign in once, reuse forever (cookies + localStorage survive restarts) |
| 🔄 Multi-account + multi-provider | Manage unlimited accounts across unlimited websites from one agent |
| 🌐 Anonymous scraping | Scrape public pages with no account (gv_open_ephemeral) |
| ⌨️ Human-like interaction | Realistic typing cadence (log-normal), typo+correction, pre-click hover, burst scrolling |
| 🔌 API tools | gv_api_call (HTTP in browser session), gv_eval_js, gv_get_cookies |
| 🩺 Session health check | gv_check_session tells you if login is still valid |
| 👁️ Vision support | Tools return PNG screenshots so the LLM can see the page |
| 🔒 Optional encryption at rest | AES-256-GCM encrypted profile archives with the key in your OS keychain |
| 🤖 LLM-agnostic | Works with Claude, GPT, Gemini, or any model your MCP client supports |
Quick start¶
Step 1 — Install (requires Python 3.11+):
Step 2 — Connect your AI agent — see Getting Started → Connect
Step 3 — Try it — ask your agent: "List available Ghostvault providers."
Prefer a one-command installer?
Then point your AI agent at Ghostvault. See Getting Started → for the full walkthrough.
Where to go next¶
- New to Ghostvault? Start with Getting Started — install, connect your agent, sign in to your first account.
- Want to scrape a public page? Read Anonymous scraping.
- Need to log in to a non-Google site? Read Custom providers.
- Configuring anti-detect settings? See Advanced → Camoufox config schema and Device profile templates.
- Looking for a specific tool? Check the Tool reference.
Project status¶
Ghostvault is at v0.1-beta with 42 MCP tools. See the Roadmap for what's planned.
⚠️ Beta software — core features work and are tested, but expect rough edges. API may change before v1.0.
Known issue: macOS Retina/HiDPI
On Retina displays, the Camoufox browser window renders UI elements too large and content overflows (requires horizontal scrolling). This is a Camoufox upstream issue — it affects the browser directly, not just Ghostvault. We are investigating workarounds. Non-Retina displays are unaffected.