Skip to main content
Glama
Ghostvault

Ghostvault

by mienetic

πŸ‘» Ghostvault

Source-available MCP server for managing browser sessions on any website through your AI agent β€” powered by Camoufox.

CI License: Apache 2.0 + Commons Clause Python 3.11+ MCP Beta

Let Claude Desktop, Cursor, Cline, or any MCP-compatible agent 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 anti-detect fingerprint and a persistent session that survives restarts.

Quick start Β· How it works Β· Tools Β· Docs Β· FAQ Β· Contributing


Why Ghostvault

Managing multiple accounts across websites from automation is painful:

  • πŸ”’ Anti-bot detection flags headless browsers, datacenter IPs, and behavioral patterns

  • πŸ” Account hopping requires re-authentication every time

  • 🌐 Login-gated sites don't expose API access

  • πŸ€– Detecting login options (SSO vs form) and choosing the right path is manual

Ghostvault solves this by giving your AI agent a real, anti-detect browser per account β€” with sessions that persist between restarts, fingerprints that don't drift, and a provider system that works with any website (not just Google).

Related MCP server: browser-auth-mcp

Features

  • 🎭 Locked fingerprints β€” each account always looks like the same device (Camoufox C-level spoofing + persisted noise seeds + advanced injection: locale, timezone, fonts, WebGL, WebRTC gate, battery, media devices)

  • 🧩 Presets + advanced config β€” balanced / stealth / minimal presets + 105 Camoufox config keys + 10 device profile templates (macbook, thinkpad, surface, ...)

  • πŸ”Œ Provider-agnostic login β€” built-in providers (google, github, facebook) + create custom providers for any website via gv_create_provider; scan login pages for SSO options with gv_detect_login_options

  • πŸ—οΈ 3 login levels β€” Level 1 (manual), Level 2 (form auto-fill via login_steps), Level 3 (record user's login actions β†’ replay automatically next time)

  • ⌨️ Human-like interaction β€” realistic typing cadence (log-normal distribution), typo+correction, pre-click hover, burst scrolling; 3-layer humanize policy (off / recommended / always)

  • 🌐 Anonymous scraping β€” gv_open_ephemeral opens a throwaway session (no account, no login) for public pages

  • πŸ”Œ API tools β€” gv_api_call (HTTP in browser session), gv_eval_js (run JS in page), gv_get_cookies

  • 🩺 Session health check β€” gv_check_session tells you if login is still valid (cookie + probe URL)

  • πŸ” Persistent sessions β€” sign in once per account, then reuse forever (cookies + localStorage survive restarts)

  • πŸ”„ Multi-account + multi-provider β€” manage unlimited accounts across unlimited websites from one agent

  • πŸ‘οΈ Vision support β€” tools return PNG screenshots so the LLM can see the page

  • πŸ“‹ Self-debugging β€” structured JSONL logs of every action

  • 🏠 Local-first β€” sessions, cookies, and fingerprints live on your machine; nothing is ever sent anywhere

  • πŸ”’ Optional encryption at rest β€” AES-256-GCM + OS keychain

  • ⏱️ Auto-close & auto-lock β€” close + re-encrypt after each task or after N idle minutes

  • πŸ”‘ Private/public profiles β€” password gate + 5-attempt wipe

  • πŸ€– LLM-agnostic β€” Claude, GPT, Gemini, or any MCP-compatible model

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_fill_input, gv_api_call,           β”‚
β”‚   gv_open_ephemeral, gv_get_cookies,    β”‚
β”‚   gv_setup_password, gv_unlock, ...     β”‚
β”‚                                                 β”‚
β”‚  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.


Quick start

Step 1 β€” Install (requires Python 3.11+):

pip install --pre ghostvault
python -m camoufox fetch    # download the browser binary (~120 MB, one-time)

Step 2 β€” Connect your AI agent:

Add Ghostvault to your MCP client config. Find your Python path:

which python3    # use this exact path below

Then add to your client config (see Connect your agent for each client's file location):

{
  "mcpServers": {
    "ghostvault": {
      "command": "/absolute/path/to/python3",
      "args": ["-m", "ghostvault"]
    }
  }
}

Step 3 β€” Try it:

Restart your agent and say: "List available Ghostvault providers."

The agent should respond with the built-in providers (google, github, facebook, generic).

That's it. No server to start, no port to manage β€” Ghostvault runs as a subprocess spawned by your AI client.


Prefer a one-command installer? (installs everything + auto-configures Claude Desktop / Cursor)

macOS / Linux (in a terminal):

curl -fsSL https://raw.githubusercontent.com/mienetic/Ghostvault/main/install.sh | bash

Windows (in PowerShell):

irm https://raw.githubusercontent.com/mienetic/Ghostvault/main/install.ps1 | iex

The installer automatically:

  1. πŸ“₯ Clones Ghostvault into ~/.ghostvault-app (or %USERPROFILE%\.ghostvault-app on Windows)

  2. 🐍 Creates an isolated Python virtualenv (doesn't touch your system Python)

  3. πŸ“¦ Installs Ghostvault + all dependencies

  4. 🦊 Downloads the Camoufox browser binary (~120 MB, one-time)

  5. βš™οΈ Writes the MCP config for Claude Desktop and/or Cursor if they're installed

Then restart Claude Desktop / Cursor β€” Ghostvault's tools appear. That's it. πŸŽ‰

Requirements: Python 3.11+ (download) and git. On macOS, run xcode-select --install first if git isn't installed. On Windows, check "Add Python to PATH" during the Python installer.

Update

# macOS / Linux
~/.ghostvault-app/update.sh

# Windows (PowerShell)
powershell -File "$env:USERPROFILE\.ghostvault-app\update.ps1"

Ghostvault also checks automatically on startup and prints a notice if a new version is available β€” so you'll never be silently out of date.

Uninstall

# macOS / Linux
bash ~/.ghostvault-app/uninstall.sh

On Windows, just delete the install dir and the data dir manually:

Remove-Item -Recurse -Force "$env:USERPROFILE\.ghostvault-app"
Remove-Item -Recurse -Force "$env:USERPROFILE\.ghostvault"   # sessions (optional)

Then remove the ghostvault entry from your Claude Desktop / Cursor config by hand.

Removes the install dir + the Ghostvault entry from your client configs. (On macOS/Linux the script asks before deleting session data, since ~/.ghostvault contains your Google sessions.)


Connect your agent

πŸ’‘ If you ran the one-line installer above, it already wrote the config for Claude Desktop and Cursor. Just restart those apps and you're done β€” skip to Usage. The steps below are only needed if you installed manually, or want to connect a different agent.

Ghostvault is an MCP server, so any MCP-compatible client can connect. Ready-to-copy config files for each client live in examples/ β€” see examples/README.md for the full cheat-sheet of where each file goes and the JSON shape each client expects.

⚠️ Use an absolute path to your Python. Clients run the server as a subprocess and don't inherit your shell PATH, so a bare python won't be found. After installing, find the right interpreter:

  • One-line installer: ~/.ghostvault-app/.venv/bin/python

  • Manual install: run which python in the venv where you installed Ghostvault, or use /usr/bin/python3, /opt/homebrew/bin/python3, etc.

Supported clients

Client

Example file

Config location

Claude Desktop

claude_desktop_config.json

~/Library/Application Support/Claude/ (macOS), %APPDATA%\Claude\ (Windows), ~/.config/Claude/ (Linux)

Cursor

cursor_config.json

~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project)

Cline (VS Code)

cline_mcp_settings.json

~/.cline/data/settings/cline_mcp_settings.json (note extra disabled/autoApprove fields)

VS Code (Agent mode)

vscode_mcp.json

.vscode/mcp.json (note shape is {"servers": {...}} with type: "stdio")

ZCode

zcode_config.json

<repo>/.zcode/config.json (workspace) or ~/.zcode/cli/config.json (note nested mcp.servers)

Continue.dev

continue_dev_config.json

~/.continue/config.json under mcpServers

Claude Code (CLI)

(CLI β€” see below)

claude mcp add ...

Claude Code (CLI)

Claude Code is configured via the claude CLI rather than a JSON file:

claude mcp add --transport stdio -s user \
  -e GHOSTVAULT_HEADLESS=false \
  ghostvault -- /absolute/path/to/python -m ghostvault

Verify: claude mcp list. Scopes: -s user (all projects), -s project (shared via .mcp.json), -s local (default).

Other clients

Any MCP-compatible client works. The universal recipe:

  1. Point command at an absolute Python path that has Ghostvault installed

  2. Set args to ["-m", "ghostvault"]

  3. Optionally set env for any GHOSTVAULT_* variables (see Configuration)

The clients disagree on JSON shape β€” see the shape cheat-sheet in examples/README.md.

Remote / HTTP transport (advanced)

To serve Ghostvault over HTTP instead of stdio (e.g. for a remote client):

GHOSTVAULT_TRANSPORT=http GHOSTVAULT_PORT=8765 python -m ghostvault

Then point your client at http://127.0.0.1:8765/mcp (use the machine's IP for remote access β€” ensure you secure it).


Verify the connection

After connecting any agent, test it with a simple prompt:

"List my Ghostvault accounts."

The agent should call gv_list_accounts and return an empty list on a fresh install. If you get an error instead, check:

  • The Python path in the config is absolute and correct (ls /that/path)

  • Ghostvault is importable from that Python: /that/path/python -c "import ghostvault"

  • The Camoufox browser binary is downloaded: /that/path/python -m camoufox path

  • For stdio clients: check the client's MCP/logs panel β€” startup errors appear there

Just talk to your agent naturally. Example prompts:

  • "Sign in to my Work Google account, then read my latest 5 emails and tell me if any need an urgent reply."

  • "Switch to my Personal account and open Drive β€” list my recent files."

  • "Open Notion using my Work Google login and create a new page called 'Weekly review'."

  • "Take a screenshot of the current page so I can see what's happening."

The agent calls the right tools. On the first sign-in of a new account, a browser window opens for you to complete login (Google will likely ask for 2FA β€” this is normal).

Typical first-time flow

1. You:   "Create a Google account called Work"
   Agent: calls gv_create_account β†’ "Done. Now sign in."

2. You:   "Sign in to Work"
   Agent: calls gv_sign_in β†’ a browser window opens
   You:   complete Google login + 2FA in that window
   Agent: "Signed in as you@gmail.com."

3. You:   "Read my latest emails"
   Agent: calls gv_read_gmail β†’ returns inbox summary

4. You:   "Now switch to Personal and open Drive"
   Agent: calls gv_switch_account + gv_open_url

Tool reference

Anonymous scraping (2 tools) β€” no account needed

Tool

Description

gv_open_ephemeral

Open a throwaway Camoufox session (no profile, no login) β€” url, headless, proxy, block_images

gv_close_ephemeral

Close an ephemeral session + free resources (defaults to active)

Provider management (5 tools) β€” custom login recipes

Tool

Description

gv_create_provider

Create a custom login recipe for any website (Level 1)

gv_list_providers

List all providers (built-in + custom) with capability flags

gv_get_provider

Show one provider's full config

gv_update_provider

Update a custom provider (refuses built-ins)

gv_delete_provider

Delete a custom provider (refuses built-ins)

Login scanning + credentials (3 tools)

Tool

Description

gv_detect_login_options

Scan a page for SSO buttons, form fields, 2FA, captcha β€” returns recommendation

gv_set_credentials

Store credentials (username/password) for Level 2 auto-fill

gv_get_credentials

Show stored credential keys (values masked)

Session health + API (4 tools)

Tool

Description

gv_check_session

Check if session is still authenticated (cookie + probe URL)

gv_api_call

HTTP request using browser session (cookies + TLS fingerprint)

gv_eval_js

Run JavaScript in the page (extract tokens, call site JS)

gv_get_cookies

Read browser cookies (masked values)

Once open, all browser tools work on the ephemeral session unchanged β€” gv_open_url, gv_get_page_content, gv_screenshot, gv_get_page_links, gv_click_element, gv_fill_input, gv_scroll, gv_press_key. The session is set as the active target automatically.

Accounts & lifecycle (18 tools)

Tool

Description

gv_list_accounts

List accounts + which is active + statuses (private hidden when locked)

gv_create_account

Create a slot with a locked fingerprint + advanced config (preset, locale, humanize, ...)

gv_update_account_config

Tweak advanced fingerprint config post-creation (identity stays locked; reopen to apply)

gv_sign_in

Open a login window for the user (handles 2FA)

gv_open_account

Open the browser reusing a saved session (no login window)

gv_switch_account

Change the active account

gv_get_session_status

Check if a session is running/authenticated

gv_close_account

Close a browser context (session saved)

gv_lock_account

Close + re-encrypt (session kept)

gv_sign_out

Sign out of Google (session invalidated; re-login required)

gv_delete_account

Delete account + profile + session + DB row permanently

gv_setup_password

Set a password to enable the private/public gate (browser window)

gv_unlock

Unlock the gate to access private profiles (password or browser window)

gv_logout

Lock the gate + close private contexts + switch to public

gv_get_auth_status

Check whether the gate is active and unlocked

gv_make_private

Mark a profile as private (hidden when locked)

gv_make_public

Mark a profile as public (always accessible)

Browser (9 tools)

Tool

Description

gv_open_url

Open any URL in the active account (incl. SSO-enabled sites)

gv_get_page_content

Read page text (+ optional screenshot via include_screenshot)

gv_screenshot

Capture a PNG (vision) β€” full_page option

gv_get_page_links

List visible links

gv_click_element

Click by visible text or CSS selector β€” humanize, delay_after_ms

gv_fill_input

Fill a form field β€” humanize, typing_speed_wpm, typing_variance, mistake_rate, delay_after_ms

gv_press_key

Press a key or chord (Enter, Tab, Escape, Ctrl+A, ...) β€” hold_ms, delay_after_ms

gv_scroll

Scroll in human-like bursts β€” direction, amount, humanize (good for reCAPTCHA v3)

gv_read_gmail

Read the Gmail inbox (convenience tool)

Debug (1 tool)

Tool

Description

gv_get_logs

Read recent JSONL action log entries

Full tool docstrings (what the agent sees) are in the skill/ directory (modular: 9 files covering all 42 tools).


Configuration

All settings are env vars (prefix GHOSTVAULT_), loadable from a .env file. See .env.example for the full list. Highlights:

Var

Default

Purpose

GHOSTVAULT_DATA_DIR

~/.ghostvault

Profiles, DB, logs

GHOSTVAULT_HEADLESS

false

Open a visible window (recommended for login + 2FA)

GHOSTVAULT_DEFAULT_OS

auto

Default fingerprint OS (auto = host OS, or windows/macos/linux)

GHOSTVAULT_LOGIN_TIMEOUT

300

Seconds to complete login + 2FA

GHOSTVAULT_TRANSPORT

stdio

stdio | http | sse

GHOSTVAULT_PROXY_*

(empty)

Optional global proxy (local-first otherwise)

GHOSTVAULT_LOG_LEVEL

INFO

Console log level

GHOSTVAULT_ENCRYPTION_ENABLED

false

Encrypt profile dirs at rest (see Encryption)

GHOSTVAULT_AUTO_CLOSE_AFTER_TASK

false

Close browser + re-encrypt after each tool call (minimizes exposure window)

GHOSTVAULT_AUTO_LOCK_MINUTES

0

Auto-close idle contexts after N minutes (0 = disabled)

GHOSTVAULT_WINDOW_WIDTH

1280

Browser window width in pixels (0 = let browser decide)

GHOSTVAULT_WINDOW_HEIGHT

800

Browser window height in pixels (0 = let browser decide)

GHOSTVAULT_HUMANIZE

true

Human-like cursor movement (click jitter + bezier path). Strongly recommended for login/SSO work.

GHOSTVAULT_BLOCK_WEBRTC_STRATEGY

auto

WebRTC gate: auto (block only with proxy) | true | false

GHOSTVAULT_DEFAULT_LOCALE

(empty)

Default locale for new accounts, e.g. en-US (empty = geoip/host-decided)

GHOSTVAULT_DEFAULT_TIMEZONE

(empty)

Default IANA timezone for new accounts, e.g. America/New_York (empty = geoip/host-decided)

GHOSTVAULT_HUMANIZE_POLICY

off

Humanize policy: off (agent decides) | recommended (default on, agent can disable) | always (forced on)

GHOSTVAULT_EPHEMERAL_HEADLESS

true

Ephemeral (scraping) sessions are headless by default

GHOSTVAULT_EPHEMERAL_BLOCK_IMAGES

true

Block image loading in ephemeral sessions (faster text scraping)

GHOSTVAULT_EPHEMERAL_AUTO_CLOSE_MINUTES

5

Idle timeout for ephemeral sessions (0 = disabled)

GHOSTVAULT_EPHEMERAL_MAX_CONCURRENT

3

Cap on simultaneous ephemeral sessions

Advanced fingerprint configuration

Camoufox exposes ~15 fingerprint-injection kwargs + 105 config-domain keys (battery, media devices, audio, WebGL params, screen, navigator, ...). Without Ghostvault you'd have to pass them every launch AND remember which go as constructor kwargs vs config dict keys. Ghostvault locks them into each account's fingerprint bundle, so they persist across launches alongside the identity.

The full ~105-key schema is documented at Camoufox config schema in the docs site. Use it to set raw keys like battery:level, mediaDevices:webcams, AudioContext:sampleRate via the device_config param.

Device profile templates fill in ~15 hardware-realistic keys at once β€” screen size, GPU vendor/renderer, media-device counts, battery, audio rate:

await gv.create_account(
    name="Work-MBP",
    device_profile="macbook-pro-14-m2",  # fills screen, GPU, mics, webcam, ...
    device_config={"battery:level": 0.45},  # override one key
)

Available profiles: macbook-pro-14-m2, macbook-air-13-m1, imac-24, windows-desktop-rtx, thinkpad-x1-carbon, surface-laptop-5, linux-workstation, dell-xps-13-ubuntu, generic-laptop, headless-server. See Device profile templates for the full comparison table.

A built-in consistency checker flags impossible combos (e.g. macOS with an NVIDIA GPU) β€” warnings surface in the gv_create_account response.

Presets bundle smart defaults so you don't have to learn all 15 params:

Preset

Use case

What it sets

balanced (default)

Most Google / SSO work

humanize=true, block_webrtc="auto"

stealth

Signups, new IPs, sensitive accounts

humanize=true, block_webrtc=true, disable_coop=true

minimal

Trusted sites, max speed

humanize=false, block_webrtc=false

Any explicit param you pass overrides the preset value.

Available params (all optional, all locked per-account):

Param

Type

Notes

locale

str | list[str]

e.g. "en-US" or ["en-US","en"]. First drives Intl API; rest populate Accept-Language. Overrides geoip when set.

timezone

str

IANA timezone, e.g. "America/New_York". Overrides geoip when set.

humanize

bool | float

true enables cursor humanization; a float sets max move duration in seconds.

block_webrtc

bool | "auto"

"auto" = block only when a proxy is set (prevents IP leak via STUN).

block_webgl

bool

Disable WebGL entirely. Some sites break; use sparingly.

webgl_config

list[str]

[vendor, renderer] pair to spoof, e.g. ["Apple Inc.", "Apple GPU"].

fonts

list[str]

Installed font family names to inject (on top of OS defaults).

addons

list[str]

Paths to extracted Firefox addon dirs (must contain manifest.json).

disable_coop

bool

Disable Cross-Origin-Opener-Policy β€” needed for some captcha/turnstile iframes.

block_images

bool

Block all image loading. Faster but visually inconsistent.

Smart-default rules (applied at launch time):

block_webrtc:
  explicit true/false β†’ use it
  "auto"              β†’ true if proxy present, false otherwise

locale / timezone:
  explicit value      β†’ use it, DISABLE geoip matching for that dimension
  absent + proxy      β†’ geoip=true (auto-match from proxy IP)
  absent + no proxy   β†’ host locale (current behavior)

humanize:
  explicit value      β†’ use it
  absent              β†’ global GHOSTVAULT_HUMANIZE default (true)

Example β€” stealth account in Thailand with a US proxy:

await gv.create_account(
    name="Work-US",
    os="windows",
    proxy={"server": "http://us-residential.example:8080"},
    preset="stealth",
    locale="en-US",              # match the proxy country
    timezone="America/New_York", # match the proxy country
)

Update config after creation (identity stays locked β€” only injection params change):

# Account must be closed first.
await gv.update_account_config(account_id, humanize=False, block_webrtc=True)
await gv.open_account(account_id)  # relaunch to apply

Reset a key back to default:

await gv.call("gv_update_account_config", {
    "account_id": account_id,
    "reset_keys": ["locale", "timezone"],
})

Note on IP: Camoufox (and any browser) cannot change the TCP source IP β€” that's set by the OS kernel, not the browser. Use a proxy or VPN for IP rotation. What the advanced config does lock is everything else: the browser-visible signals (locale, timezone, fonts, WebGL, WebRTC leak gate) that must match the IP's country or the account looks inconsistent. See this discussion for the full IP/fingerprint model.

Encryption at rest (optional)

By default, each account's persistent profile (which holds real Google session cookies) lives on disk as plaintext Firefox profile files. Anyone with read access to ~/.ghostvault/profiles/ can steal your sessions.

Enable encryption to store profiles as AES-256-GCM archives instead:

export GHOSTVAULT_ENCRYPTION_ENABLED=true

Or set it in your client's env block:

"env": { "GHOSTVAULT_ENCRYPTION_ENABLED": "true" }

How it works:

  • The master key is stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) β€” never on disk. It's auto-generated on first use.

  • When the browser opens, the profile is decrypted to a temp dir (wiped on close).

  • When the browser closes, the profile is re-encrypted to <account_id>.profile.enc.

  • Existing plaintext profiles are auto-migrated on first open after enabling.

Requirements & caveats:

  • Keychain backend required. On headless Linux without D-Bus / Secret Service (e.g. a bare Docker container), encryption can't store the key securely and stays disabled. Run gnome-keyring or kwallet first.

  • Losing the keychain entry = losing the profiles. The key is not derivable from anything else. There is no recovery path by design β€” that's what makes it secure.

  • The browser still sees plaintext while running. Encryption protects data at rest, not against an attacker who compromises the running session.

  • Fingerprint files stay plaintext. They describe the spoofed identity (UA, screen, etc.) but don't contain session secrets, so encrypting them isn't worth the complexity.

Private/public profiles (optional)

Ghostvault can separate profiles into public (accessible without unlocking) and private (hidden behind a password). This is an app-level visibility gate on top of encryption-at-rest.

How it works:

  1. Call gv_setup_password β€” a browser window opens for you to set a password

  2. Mark sensitive profiles as private: gv_make_private({account_id})

  3. When locked, gv_list_accounts hides private profiles; browser tools refuse to open them

  4. Call gv_unlock({password}) to access private profiles (stays unlocked until gv_logout or server restart)

Brute-force protection:

  • 3 wrong passwords β†’ warning with remaining attempts

  • 5 wrong passwords β†’ all private profiles permanently deleted + password reset

  • Public profiles are never affected by failed attempts

This is different from encryption-at-rest: encryption protects the disk (someone steals the laptop); the private/public gate protects access (someone sits at your unlocked machine and tries to use private Google accounts via the agent).

Remote (HTTP transport)

For remote access instead of the default stdio transport:

GHOSTVAULT_TRANSPORT=http GHOSTVAULT_PORT=8765 python -m ghostvault

Point your client at http://127.0.0.1:8765/mcp.

Anonymous scraping (no account needed)

Not every task needs a managed account. gv_open_ephemeral launches a throwaway Camoufox session: no profile, no DB row, no login, random identity per session, tempdir removed on close. Once open, all browser tools work on it unchanged β€” it just becomes the active target.

# Open a throwaway browser + navigate to a public page
await gv.open_ephemeral(url="https://news.ycombinator.com")

# All browser tools work β€” no changes needed
content = await gv.get_page_content(include_screenshot=True)
links = await gv.get_page_links(limit=20)
await gv.scroll(direction="down", amount=3)

# Done β€” close frees the browser + removes the tempdir
await gv.close_ephemeral()

Mix anonymous scraping with managed accounts:

# Scrape a public page anonymously...
await gv.open_ephemeral(url="https://example.com/public-data")
data = await gv.get_page_content()
await gv.close_ephemeral()

# ...then switch to a managed account for authenticated work
await gv.open_account("acc_abc123")
await gv.open_url("https://mail.google.com")

Ephemeral defaults are tuned for scraping (override per call):

Setting

Default

Why

headless

true

Scraping doesn't need a visible window (opposite of managed accounts)

block_images

true

Faster text scraping; turn off if you need screenshots

humanize

false

No cursor movement needed for read-only scraping

auto_close_minutes

5

Short idle timeout β€” abandoned sessions clean themselves up

max_concurrent

3

Cap on simultaneous ephemeral sessions (each is a full Firefox process)

Override via env vars (GHOSTVAULT_EPHEMERAL_*) or per call:

# Visible browser + keep images for screenshot-based scraping
await gv.open_ephemeral(url="...", headless=False, block_images=False)

When to use ephemeral vs managed accounts:

Scenario

Use

Scrape a public page (news, docs, pricing)

gv_open_ephemeral

Login-required site (Gmail, Drive, SSO)

Managed account (gv_create_account + gv_sign_in)

Fill a public form (contact, signup-free download)

gv_open_ephemeral

Read Gmail / access Google services

Managed account

Captcha-protected scrape target

gv_open_ephemeral + humanize=True via the proxy param

See examples/scripts/scrape_public_page.py and scrape_with_pagination.py for complete runnable examples.

Human-like interaction (anti-bot typing + clicks)

Camoufox's humanize=True covers mouse-movement bezier curves at the C++ layer (so isTrusted=true and the cursor path looks human). It does NOT cover:

  • Typing cadence β€” Playwright's fill() pastes the whole string in one input event; keyboard.type(text, delay=N) uses a constant delay between every char, which is itself a bot tell.

  • Inter-keystroke variance β€” real humans speed up on common bigrams ("th", "ing") and slow down on rare ones.

  • Occasional typos + corrections β€” a perfect string with zero Backspaces is suspicious for long inputs.

  • Pre-click hover β€” Playwright's .click() moves + clicks in one gesture; real users hover for 50–500 ms before clicking.

Ghostvault fills these gaps at the Playwright layer. Every interaction tool gains optional humanization params:

Param

Type

Default

Purpose

humanize

bool

false

Type char-by-char (fill) or hover-then-click (click).

typing_speed_wpm

int

90

Target words-per-minute (40=slow, 90=avg, 150=fast).

typing_variance

float

0.35

Cadence spread 0–1 (log-normal sigma). 0=constant, 0.35=realistic, 1=erratic.

mistake_rate

float

0.0

Chance per char to typo-then-correct (0–0.05). Produces realistic Backspace events.

delay_after_ms

int

0

Randomized pause after the action (0.7×–1.3Γ— spread).

Per-call example β€” Google login with humanized typing:

await gv.fill_input(
    target="Email", value="user@gmail.com",
    humanize=True, typing_speed_wpm=85, typing_variance=0.4,
    mistake_rate=0.02, delay_after_ms=800,
)
await gv.click_element(target="Next", humanize=True, delay_after_ms=1500)

Per-account defaults (set once, applies to all calls unless overridden):

await gv.update_account_config(account_id, humanize_typing=True, default_typing_wpm=85)
# Now every gv_fill_input on this account is humanized unless you pass humanize=False

The typing model is a log-normal distribution (the standard HCI model). For wpm=90, variance=0.35, inter-keystroke delays center around ~130 ms with occasional 300–500 ms outliers β€” matching observed human typing. With mistake_rate > 0, a fraction of characters are mistyped to a QWERTY-adjacent key, paused on briefly, then Backspace-corrected.

New tools for richer interaction:

Tool

Use case

gv_press_key

Submit with Enter, Tab between fields, Escape to dismiss, Ctrl+A to select all

gv_scroll

Human-like scroll bursts with reading pauses β€” critical for reCAPTCHA v3, which weights scroll behavior heavily

reCAPTCHA v3 warm-up pattern β€” a page that loads + immediately submits looks like a bot. Scroll, read, click around, THEN act:

await gv.open_url("https://protected-site.com")
await asyncio.sleep(3)                          # let the page settle
await gv.scroll(direction="down", amount=2)     # burst-scroll
await asyncio.sleep(2)                          # reading pause
await gv.get_page_content()                     # "engage" with content
await gv.scroll(direction="up", amount=2)       # round-trip scroll
await gv.fill_input("query", "search term", humanize=True)  # NOW act
await gv.press_key("Enter")

See examples/scripts/human_like_login.py, fill_long_form.py, and captcha_friendly_browsing.py for complete runnable examples.

Humanize policy β€” who decides?

By default, the AI agent decides per-call whether to enable humanize (based on the Decision Guide in each tool's docstring). For sensitive accounts you may want to lock this down. Ghostvault supports a 3-layer policy model:

Policy

Behavior

Use case

off (default)

Agent decides every call; per-account humanize_typing/humanize_clicks is the fallback when the agent omits the arg.

Trusted environments, fast iteration.

recommended

Humanize defaults ON; agent CAN turn it OFF explicitly by passing humanize=false.

Most real-world use β€” safety net without rigidity.

always

Humanize forced ON at the server. The agent cannot disable it, even by passing humanize=false.

Sensitive accounts (ads, payments) where a single mistake = ban.

Resolution order (highest wins):

1. Per-account humanize_policy  (set via gv_update_account_config)
2. Global GHOSTVAULT_HUMANIZE_POLICY  (env var)
3. "off"  (default β€” agent decides)

Set it globally (applies to all accounts):

# In .env or your client's env block:
GHOSTVAULT_HUMANIZE_POLICY=recommended

Set it per-account (overrides global):

# Force humanize on for this sensitive account β€” agent can't disable it.
await gv.update_account_config(account_id, humanize_policy="always")

The tool result includes the effective humanize value so the agent (and you) can verify what actually ran:

{"filled": "Email", "humanize": true, "typing_speed_wpm": 85}

Manual install (alternative)

Ghostvault is on PyPI (beta) β€” install with pip install --pre ghostvault. Requires Python 3.11+.

git clone https://github.com/mienetic/Ghostvault.git
cd Ghostvault
pip install -e .

# Download the Camoufox browser binary (~120 MB, one-time)
python -m camoufox fetch

For development (includes test + lint tooling):

pip install -e ".[dev]"

Then add Ghostvault to your client config manually. Use the Python from your environment as the command β€” for example, the venv python if you installed into one.

Claude Desktop β€” edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "ghostvault": {
      "command": "/absolute/path/to/your/python",
      "args": ["-m", "ghostvault"],
      "env": {
        "GHOSTVAULT_HEADLESS": "false"
      }
    }
  }
}

Cursor β€” edit .cursor/mcp.json:

{
  "mcpServers": {
    "ghostvault": {
      "command": "/absolute/path/to/your/python",
      "args": ["-m", "ghostvault"]
    }
  }
}

Restart your client after editing.


Programmatic use (SDK)

For scripts that want to call Ghostvault without an LLM in the loop (run inside the cloned repo, after pip install -e . above):

pip install -e ".[sdk]"
import asyncio
from ghostvault_sdk import GhostvaultClient

async def main():
    async with GhostvaultClient() as gv:
        await gv.create_account(name="Work", os="macos")
        accounts = await gv.list_accounts()
        print(accounts)

asyncio.run(main())

See the examples/ directory for comprehensive examples:

Example

What it demonstrates

scripts/sdk_all_tools.py

Every gv_* tool called via SDK (42 tools)

scripts/custom_provider_demo.py

Create a custom provider recipe for any website + list/delete providers

scripts/detect_login_demo.py

Scan a login page for SSO buttons, form fields, 2FA, captcha + get recommendation

scripts/record_login_demo.py

Level 3: record a login flow β†’ replay automatically next time

scripts/session_health_demo.py

Check session health + API call + JS eval + cookie reading

scripts/human_like_login.py

Human-like login (any provider) with realistic typing cadence (85 wpm, 2% typos)

scripts/fill_long_form.py

Multi-field form with per-field typing speeds + Tab navigation + Shift+Tab to go back

scripts/captcha_friendly_browsing.py

reCAPTCHA v3 warm-up pattern: scroll, read, click, THEN act

scripts/scrape_public_page.py

Anonymous one-shot scrape: open_ephemeral β†’ read + screenshot + links β†’ close (no account)

scripts/scrape_with_pagination.py

Multi-page scrape on a persistent ephemeral session: loop {read, scroll, click Next}

scripts/sdk_private_public.py

Private/public gate flow via SDK (setup, lock, unlock, logout)

scripts/check_gmail.py

End-to-end: create + sign in + read Gmail + close

scripts/mcp_e2e_test.py

MCP protocol test: create + sign in + read Gmail

scripts/mcp_security_test.py

Encryption + auto-close + auto-lock + sign_out + delete

agent_prompts.md

Copy-paste prompts for Claude Desktop / Cursor / ZCode (all 42 tools)


FAQ

No. Each profile is a container that holds sessions for any website equally. Use gv_create_account(provider="github") + gv_sign_in to login GitHub directly. Or use gv_create_account(provider="my_custom_site") with a custom provider you created via gv_create_provider. Google is just one of the built-in providers β€” it's not a "parent" that other providers depend on.

The agent can detect what login options a page offers by calling gv_detect_login_options(url) β€” it scans for SSO buttons, form fields, 2FA, and captcha, then recommends a login path.

Ghostvault uses Camoufox, a Firefox fork with C-level fingerprint spoofing. With locked fingerprints + humanized interaction + your home IP, each account looks like a genuine device. That said:

  • First-time login often triggers 2FA β€” the site sees a new device. This is expected.

  • Don't share IPs across many accounts β€” one account per proxy/IP is the safe ratio.

  • Use humanize=true on login forms β€” instant paste typing is the #1 bot tell.

  • No tool is undetectable β€” behavioral ML (reCAPTCHA v3) and IP reputation still apply.

Ghostvault gives you the tools to be safe; how you use them is your responsibility. See LICENSE for the full liability disclaimer.

Yes, but with caveats:

  • You'll need a residential/mobile proxy per account (datacenter IPs get flagged).

  • Login requires a visible window β€” on a headless server, use headless='virtual' (Xvfb) or VNC.

  • Configure the proxy before the first login (the session is tied to the IP + fingerprint).

For most users, running locally is simpler and safer. Remote HTTP transport (GHOSTVAULT_TRANSPORT=http) is available if needed.

Yes β€” any website. Built-in providers: Google, GitHub, Facebook, generic. Custom providers: create via gv_create_provider for any site (your bank, internal apps, SaaS tools). Each profile holds sessions for all websites equally.

Once logged in, call gv_open_url with any URL β€” the agent can navigate, click, fill forms, call APIs, and read pages.

Those are agent frameworks (they provide the LLM↔browser reasoning loop). Ghostvault is a tool provider β€” it exposes browser tools via MCP that any agent framework (or plain Claude Desktop) can call. You can even combine them: use Ghostvault for the stealth Google sessions and let your favorite agent framework drive the pages.

Ghostvault uses Camoufox (Firefox/Juggler), while browser-use 0.13+ requires CDP (Chromium-only) β€” so they don't directly interoperate, but they solve different problems.

Everything stays local under ~/.ghostvault/:

  • profiles/ β€” per-account Camoufox profiles (cookies, localStorage, fingerprint lock)

  • logs/ghostvault.jsonl β€” structured debug log

  • browserver.sqlite β€” account metadata only (no sessions)

Nothing is ever sent to a remote server except the browser traffic itself (which exits via your home IP, or your configured proxy). Ghostvault has no telemetry, no analytics, no phone-home.

You need to sign in first. Tell the agent: "Sign in to [account name]". A browser window opens; complete Google login there. After that, the account is active and the browser tools work. See Typical first-time flow.


Troubleshooting

Symptom

Fix

Login window doesn't appear

Set GHOSTVAULT_HEADLESS=false in .env or your client config env block

gv_read_gmail returns empty

Gmail's DOM changes often β€” fall back to gv_open_url to mail.google.com + gv_get_page_content with include_screenshot=true

"Session not authenticated"

The session expired β€” re-run gv_sign_in for that account

Agent action had no effect

Call gv_get_logs and/or gv_screenshot to see what the browser shows

Install fails on camoufox fetch

Network issue β€” retry with python -m camoufox fetch, or skip and run it later

Two windows for same account

Not possible β€” Ghostvault enforces one context per account. Switch accounts instead.


Important notes

  • First-time login = new device. Google sees a new fingerprint/IP, so expect a 2FA challenge. This is one-time per account.

  • Local-first by default. Traffic exits via your home IP. If you move Ghostvault to a server, add a residential proxy and re-login.

  • One context per account. Ghostvault refuses to open two windows for the same profile (would corrupt it). Switch accounts instead.

  • Gmail scraping is best-effort. Gmail's DOM changes often; if gv_read_gmail returns empty, fall back to gv_open_url + gv_get_page_content with a screenshot.

  • Sessions are sensitive. Anyone with read access to ~/.ghostvault/ has full access to your Google accounts. Protect that directory β€” or enable encryption at rest.

  • Camoufox β‰  Firefox. Ghostvault downloads its own patched Camoufox browser (~120 MB) during install. You don't need to install Firefox separately; the two don't conflict.


Known issues

⚠️ macOS Retina/HiDPI rendering (in progress): 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.

Roadmap

Legend: 🟒 done Β· πŸ”΅ in progress Β· βšͺ planned Β· 🏁 good first issue Β· πŸ’› help wanted Β· πŸ’° needs funding


v0.1-beta (current β€” PyPI 0.1.x)

⚠️ Beta software. All features below are done and shipped. API may change before v1.0. Known issues: Retina rendering + MCP timeout.

  • 🟒 Core: per-account persistent Camoufox profiles + locked fingerprints

  • 🟒 42 MCP tools (accounts, lifecycle, browser, providers, API, scraping, debug, security)

  • 🟒 Published to PyPI β€” pip install --pre ghostvault

  • 🟒 Provider-agnostic login β€” built-in + custom providers, login scan, 3 login levels

  • 🟒 Session health check, API tools, anonymous scraping

  • 🟒 Advanced fingerprint config β€” 105 Camoufox config keys + 10 device profiles

  • 🟒 Human-like interaction β€” log-normal typing, typo+correction, hover, scroll

  • 🟒 Encryption at rest + private/public gate + profile recovery

  • 🟒 SDK client + GitHub Pages docs + one-click installer

  • 🟒 CI: lint + test + build + docs deploy + PyPI publish

v0.2 β€” Stabilize (next β€” when known issues are fixed)

  • πŸ”΅ Fix macOS Retina/HiDPI rendering

  • πŸ”΅ Fix MCP timeout for setup_password

  • βšͺ Community testing feedback β†’ bug fixes

  • βšͺ API freeze (no breaking changes after this)

  • βšͺ gv_export_session / gv_import_session β€” backup/restore

  • βšͺ gv_wait_for_element + gv_wait_for_navigation

  • 🏁 Replace ad-hoc CSS selectors with a tested strategy

v0.3 β€” Ecosystem (planned)

  • βšͺ More built-in providers (Microsoft, Apple, Twitter, LinkedIn)

  • βšͺ Per-site action packs (Gmail, Drive, Calendar, Notion, GitHub)

v1.0 β€” Production (planned)

  • βšͺ Docker image + docker-compose

  • βšͺ Audit log (who did what, when)

  • βšͺ Rate limiting + concurrent account limits

  • βšͺ Plugin system for per-site action packs

  • βšͺ Independent security review πŸ’°

v1.x+ β€” Scale (ideas)

  • βšͺ Vision-based action suggestion (LLM looks at screenshot β†’ proposes next action)

  • βšͺ Cloud-hosted option (managed Ghostvault as a service) πŸ’°

  • βšͺ Mobile device profiles (iPhone Safari, Android Chrome)

  • βšͺ Proxy rotation per account

Contributing to the roadmap

  • Pick anything marked 🏁 (good first issue) or πŸ’› (help wanted) β€” open a PR.

  • Have a use case we're missing? Open a discussion.


Contributing

Contributions welcome! See CONTRIBUTING.md for setup, conventions, and how to add a new tool.

pip install -e ".[dev]"
pytest -q
ruff check .

Adding a tool

  1. Add the input model to src/ghostvault/inputs.py

  2. Add the logic to src/ghostvault/tools.py (raise ToolError for expected failures)

  3. Register it in src/ghostvault/server.py with @mcp.tool(name=..., annotations=...) and a thorough docstring

  4. Add a test under tests/

The fingerprint lock is an invariant β€” any change that breaks it causes every account to look like a new device. tests/test_fingerprint.py guards it; keep it green.


Development

git clone https://github.com/mienetic/Ghostvault.git
cd Ghostvault
pip install -e ".[dev]"
python -m camoufox fetch   # one-time browser download
pytest -q                  # 17 unit tests
ruff check .               # lint

License

Apache 2.0 + Commons Clause β€” free to use, modify, and distribute for personal, research, educational, and internal use. Selling the software as a product or service (SaaS, paid hosting, paid consulting) requires a commercial license.

What's allowed: internal use, research, education, consulting, modifying, forking.

What's not allowed (without commercial license): selling the software itself, offering it as a paid SaaS, bundling it into a paid product.

Disclaimer: The authors are not responsible for any misuse of this software. You are solely responsible for complying with all applicable laws and terms of service. See LICENSE for the full liability disclaimer.


⚠️ Use responsibly. Ghostvault is a tool for managing your own accounts. Don't use it to access accounts you don't own, violate terms of service, or do anything illegal. You are responsible for how you use it.

Available Tools

42 tools
gv_api_callHTTP API Call (browser session)A

Make an HTTP request using the active account's browser session.

Uses the browser's cookies + TLS fingerprint, so the request looks identical to one made by the page itself. Bypasses cookie-based auth and TLS fingerprinting. Faster than navigating a page when you just need data from an API endpoint.

Args: method: HTTP method β€” GET, POST, PUT, PATCH, DELETE. url: The absolute URL to request. headers: Optional dict of HTTP headers (e.g. {"Authorization": "Bearer ..."}). body: Optional request body. Dict/list β†’ JSON-encoded automatically; string β†’ sent as-is. use_session: If True (default), the browser's cookies + TLS are used. Set False to send a "clean" request (no cookies). timeout_ms: Request timeout in ms (default 30000).

Returns {status, status_text, headers, body, url}.

Inputs: url (required), method (required), body, headers, +2 more. Returns: result

gv_check_sessionCheck Session HealthA
Read-only

Check whether the account's browser session is still authenticated.

Uses a 2-layer check: cookie expiry (fast) + probe URL redirect (accurate). Returns the health status (active / likely_active / expired / unknown), a reason, and the recommended action.

The browser context must be open (call gv_open_account first) for an accurate check. If closed, returns 'unknown'.

Args: account_id: The account id to check. Omit to check the active account.

Inputs: account_id. Returns: result

gv_click_elementClick ElementA

Click an element on the current page by visible text or CSS selector.

Text matching is case-insensitive and substring-based (preferred). If no text matches, the target is tried as a CSS selector. After clicking, waits for the page to settle and returns a preview of the new page.

Args: target: Visible text of the element (preferred) OR a CSS selector. timeout_ms: Max wait time in ms (default 10000). humanize: When true, hover briefly before clicking + jitter the click point. Defaults to the account's humanize_clicks setting (off if unset). Recommended for anti-bot-sensitive sites. delay_after_ms: Pause for a randomized ~this many ms after the click (0.7×–1.3Γ— spread). 0 = no delay.

DECISION GUIDE β€” when to set humanize=true: β€’ Google / SSO login buttons ("Next", "Sign in") β†’ ALWAYS β€’ Captcha-protected pages (reCAPTCHA, Cloudflare) β†’ ALWAYS β€’ Form submit buttons on banking / payments β†’ ALWAYS β€’ Search buttons, nav links on trusted sites β†’ optional (can skip) β€’ One-time quick clicks in a familiar dashboard β†’ can skip

Note: If the account's humanize_policy is "always", humanize is forced on regardless of what you pass here.

Returns the clicked target, whether humanize was applied, and a page preview.

Inputs: target (required), humanize, timeout_ms, delay_after_ms. Returns: result

gv_close_accountClose Google Account BrowserA

Close the running browser context for an account (keeps its session saved).

The persistent profile stays on disk, so reopening reuses the same login. Use this to free resources when done with an account.

Args: account_id: The account id to close.

Inputs: account_id (required). Returns: result

gv_close_ephemeralClose Anonymous Browser SessionA
Destructive

Close an ephemeral session and free its resources.

Removes the tempdir + tears down the browser process. If the closed session was the active target, the active slot falls back to another running context (or None).

Args: session_id: The session id from gv_open_ephemeral. Omit to close the currently-active session.

Returns the closed id + the new active target.

Inputs: session_id. Returns: result

gv_create_accountCreate Google Account SlotA
Destructive

Create a new managed account slot with a locked fingerprint + advanced config.

Generates a fresh, pinned fingerprint + empty persistent profile. The account is NOT signed in yet β€” call gv_sign_in next to open a login window.

Args: name: Human label for the account (e.g. "Work"). os: Pinned fingerprint OS β€” "windows" | "macos" | "linux". Defaults to server config (or the device profile's recommended OS if device_profile is set). proxy: Optional Playwright-style proxy dict for this account only. provider: Identity provider β€” "google" (default), "github", etc. preset: Bundle of advanced-config defaults β€” "balanced" (default) | "stealth" | "minimal". Explicit params below override the preset. locale: Locale(s) for Intl + Accept-Language, e.g. "en-US" or ["en-US","en"]. When set, overrides geoip-based locale matching. timezone: IANA timezone, e.g. "America/New_York". When set, overrides geoip. humanize: Human-like cursor movement. True (default in balanced) | False | float (max seconds for the move). block_webrtc: Block WebRTC to prevent IP leak. True | False | "auto" (auto = block only when a proxy is set; the preset default). block_webgl: Disable WebGL entirely. Some sites break; use sparingly. webgl_config: [vendor, renderer] pair to spoof, e.g. ["Apple Inc.", "Apple GPU"]. fonts: List of installed font family names to inject (on top of OS defaults). addons: List of paths to extracted Firefox addon dirs (must have manifest.json). disable_coop: Disable Cross-Origin-Opener-Policy β€” needed for some captcha/turnstile iframes. (stealth preset sets this.) block_images: Block all image loading. Faster but visually inconsistent. device_profile: A realistic hardware template that fills in ~15 Camoufox config keys at once (screen size, GPU vendor/renderer, media-device counts, battery level, audio sample rate). One of: macbook-pro-14-m2, macbook-air-13-m1, imac-24, windows-desktop-rtx, thinkpad-x1-carbon, surface-laptop-5, linux-workstation, dell-xps-13-ubuntu, generic-laptop, headless-server. Recommended for maximum fingerprint consistency. device_config: Raw dict of Camoufox config-domain keys (battery:, mediaDevices:, navigator.hardwareConcurrency, ...) to override or augment the chosen device_profile. See the Advanced Configuration docs for the full ~100-key schema.

Returns the new account id, resolved config, and any consistency warnings.

Inputs: name (required), os, fonts, proxy, +13 more. Returns: result

gv_create_providerCreate Custom ProviderA
Destructive

Create a custom login provider recipe for any website.

Once created, use it with gv_create_account(provider=name) or gv_sign_in(account_id, provider=name). The provider recipe is stored in ~/.ghostvault/providers.json and shared across all accounts.

Args: name: Unique provider name (e.g. "my_bank"). Cannot shadow built-ins. login_url: The URL to navigate to for login (e.g. "https://app.example.com/login"). success_url_fragments: URL fragments indicating login succeeded (e.g. ["app.example.com/dashboard"]). auth_cookie_names: Cookie names that prove authentication (e.g. ["session_id"]). auth_cookie_domain: The domain to read auth cookies from (e.g. "https://app.example.com"). logout_url: Optional direct logout URL. If None, user must logout manually. session_probe_url: Optional URL to check if session is still valid. login_url_fragments: URL fragments indicating redirect to login (session expired). description: Human-readable description of this provider.

Inputs: name (required), login_url (required), auth_cookie_names (required), auth_cookie_domain (required), +5 more. Returns: result

gv_delete_accountDelete Google Account (remove all data)A
Destructive

Delete an account and all its data from Ghostvault.

Removes the profile directory, encrypted archive (if any), fingerprint file, and the DB row. Cannot delete a running account β€” lock/close it first. This does NOT sign the account out of Google; use gv_sign_out first if you want to invalidate the session server-side.

Args: account_id: The account id to delete.

Inputs: account_id (required). Returns: result

gv_delete_providerDelete Custom ProviderA
Destructive

Delete a custom provider. Built-in providers cannot be deleted.

Args: name: The provider name to delete.

Inputs: name (required). Returns: result

gv_detect_login_optionsDetect Login Options on PageA
Read-only

Scan the current page (or a URL) for available login options.

Detects SSO buttons (Google, GitHub, Facebook, etc.), username/password form fields, 2FA/OTP fields, and captcha. Returns a recommendation on which login path to take.

Use this BEFORE gv_sign_in when you're not sure what the page offers β€” it helps the agent decide whether to auto-fill, click an SSO button, or let the user log in manually.

DECISION GUIDE β€” what to do with the result:

  • recommendation="sso:google" β†’ click the SSO button for that provider

  • recommendation="form" β†’ use gv_sign_in with stored credentials

  • recommendation="ask_user" β†’ multiple SSO options found; ASK the user which provider they want to use

  • recommendation="manual" β†’ no form/SSO detected; let user do it manually (the browser window is already open)

In ALL cases, the session is saved automatically β€” the user only needs to log in once per account.

Args: url: Optional URL to navigate to before scanning. If omitted, scans the current page.

Inputs: url. Returns: result

gv_eval_jsEvaluate JavaScript in PageA

Run JavaScript in the active page and return the result.

Use cases:

  • Extract CSRF tokens: document.querySelector('meta[name=csrf-token]').content

  • Call site JS: window.app.generateSignature(payload)

  • Read state: localStorage.getItem('auth_token')

  • Read hidden fields: document.querySelector('#token').value

The script can be an expression or a function. If arg is provided, it's passed as the first parameter to a function script.

Args: script: JS expression or arrow function. arg: Optional argument to pass to a function script.

Returns whatever the JS evaluates to.

Inputs: script (required), arg. Returns: result

gv_fill_inputFill Input FieldA

Fill a form input on the current page.

Tries to find the input by its label text first (case-insensitive, substring match), falling back to a CSS selector.

By default this uses Playwright's instant paste (fast, but detectable). Set humanize=true to type one character at a time with a realistic log-normal cadence + optional typos β€” strongly recommended for Google login forms and any anti-bot-protected input.

Args: target: Visible label text of the field (preferred) OR a CSS selector. value: The text to type into the field. timeout_ms: Max wait time in ms (default 10000). humanize: Type char-by-char with realistic cadence. Defaults to the account's humanize_typing setting (off if unset). typing_speed_wpm: Target words-per-minute (40=slow, 90=avg, 150=fast). Defaults to the account's default_typing_wpm or 90. typing_variance: Cadence spread 0–1 (0=constant, 0.35=realistic, 1=erratic). Default 0.35. mistake_rate: Chance per char to typo-then-correct (0–0.05). Produces realistic Backspace events. Default 0 (off). delay_after_ms: Pause for a randomized ~this many ms after typing.

DECISION GUIDE β€” when to set humanize=true: β€’ Google / SSO login forms (email, password) β†’ ALWAYS (instant paste is the #1 bot detection tell) β€’ Captcha-protected form fields β†’ ALWAYS β€’ Banking / payment forms β†’ ALWAYS β€’ 2FA / OTP code fields β†’ optional (short codes, paste is fine) β€’ Search boxes on trusted sites (Gmail, Drive) β†’ optional β€’ Quick one-off inputs in a familiar dashboard β†’ can skip

Recommended values by scenario: β€’ Login email: humanize=true, wpm=85, variance=0.4, mistakes=0.02 β€’ Login password: humanize=true, wpm=65, variance=0.5, mistakes=0.0 β€’ Long form: humanize=true, wpm=90, variance=0.35, mistakes=0.01 β€’ Search box: humanize=false (or omit)

Note: If the account's humanize_policy is "always", humanize is forced on regardless of what you pass here.

Returns the target, char count, and whether humanize was applied.

Inputs: value (required), target (required), humanize, timeout_ms, +4 more. Returns: result

gv_get_auth_statusGet Auth StatusA
Read-only

Check whether the private/public password gate is active and unlocked.

Returns gate_enabled (bool), unlocked (bool), and a human-readable message. If no password has been set, the gate is off and all profiles are public.

Inputs: no named parameters. Returns: result

gv_get_cookiesRead Browser CookiesA
Read-only

Read cookies from the active browser context.

Cookie values longer than 20 chars are masked for security. Use this for debugging sessions or understanding what the site has set.

Args: domain: If set, only cookies matching this domain are returned. If omitted, all cookies are returned.

Inputs: domain. Returns: result

gv_get_credentialsShow Stored Credential KeysA
Read-only

Show which credential keys are stored for an account (values are masked).

Args: account_id: The account id.

Inputs: account_id (required). Returns: result

gv_get_logsGet Debug LogsA
Read-only

Return the most recent debug log entries (for troubleshooting).

Each entry records a tool call / browser action with timestamp, account, action, status, duration, and error info. Use this when something isn't working and you need to see what happened.

Args: n: Number of recent entries to return (default 50, max 500).

Inputs: n. Returns: result

gv_get_page_contentGet Page Content (text + optional screenshot)A
Read-only

Read the current page's text content, optionally with a screenshot.

Set include_screenshot=true to ALSO receive an image of the page so you can SEE the layout β€” use this when text alone isn't enough (captcha, image buttons, complex visual structure).

Args: include_screenshot: If true, append a PNG image of the viewport. max_chars: Max characters of page text (default 20000).

Inputs: max_chars, include_screenshot.

gv_get_providerGet Provider DetailsA
Read-only

Show one provider's full configuration (login URL, cookies, etc.).

Args: name: The provider name (built-in or custom).

Inputs: name (required). Returns: result

gv_get_session_statusGet Google Session StatusB
Read-only

Check whether an account's browser session is running and authenticated.

If account_id is omitted, checks the active account.

Returns: id, name, email, running, active, status, last_login_at.

Inputs: account_id. Returns: result

gv_list_accountsList Google AccountsA
Read-onlyIdempotent

List all managed accounts and which one is currently active.

Returns each account's id, label, email, status (created/logging_in/active/ failed), whether a browser context is running, and the active account id. Use this first to discover account ids before calling other tools.

Inputs: no named parameters. Returns: result

gv_list_providersList All ProvidersA
Read-onlyIdempotent

List all providers (built-in + custom) with capability flags.

Returns each provider's name, max_login_level, needs_credentials, has_logout_url, has_session_probe, is_builtin, and description.

Built-in providers: google, github, facebook, generic.

Inputs: no named parameters. Returns: result

gv_lock_accountLock Google Account (close + re-encrypt)A

Lock an account β€” close the browser and re-encrypt its profile.

The saved session is KEPT, so reopening (gv_open_account) works without re-login. This is the manual version of auto-lock. Use it when you're done with an account for now but want to come back to it later without re-authenticating.

Args: account_id: The account id to lock.

Inputs: account_id (required). Returns: result

gv_logoutLock Private Profiles (Logout)A

Lock the private/public gate.

Closes any open private browser contexts and switches the active account to the first available public profile (or none). Private profiles become hidden again until you call google_unlock.

This does NOT sign you out of Google β€” it only locks Ghostvault's gate.

Inputs: no named parameters. Returns: result

gv_make_privateMake Profile PrivateA

Mark a profile as private (hidden when the gate is locked).

Requires the password gate to be active (call google_setup_password first).

Args: account_id: The account id to make private.

Inputs: account_id (required). Returns: result

gv_make_publicMake Profile PublicB

Mark a profile as public (accessible without unlocking).

Args: account_id: The account id to make public.

Inputs: account_id (required). Returns: result

gv_open_accountOpen Google Account Browser (reuse session)A

Open the browser context for an already-signed-in account.

Unlike gv_sign_in (which waits for you to complete login), this opens the account's persistent profile and reuses the existing saved session β€” no login window, no waiting. Use this after a sign-in has succeeded once and you've since closed the browser.

Also marks the account as active so subsequent browser tools target it.

Args: account_id: The account id to open.

Inputs: account_id (required). Returns: result

gv_open_ephemeralOpen Anonymous Browser SessionA

Open a throwaway browser session for anonymous scraping β€” NO account needed.

Launches a fresh Camoufox browser with a random identity, no persistent profile, and no DB row. Nothing survives the session β€” perfect for public pages that don't require login.

The session becomes the active target, so ALL existing browser tools work on it unchanged: gv_open_url, gv_get_page_content, gv_screenshot, gv_get_page_links, gv_click_element, gv_fill_input, gv_scroll, gv_press_key.

Defaults are tuned for scraping: headless=True, block_images=True, short 5-minute idle auto-close. Override per call if needed.

Args: url: Optional URL to navigate to immediately. Omit to start on a blank page. headless: Override the default (True). Set False to watch the browser. proxy: Optional Playwright-style proxy dict (same format as gv_create_account). block_images: Override the default (True). Set False if you need screenshots.

Returns the session id + next steps.

When done, call gv_close_ephemeral. The session also auto-closes after GHOSTVAULT_EPHEMERAL_AUTO_CLOSE_MINUTES idle (default 5).

Inputs: url, proxy, headless, block_images. Returns: result

gv_open_urlOpen URL in Google AccountA

Open a URL in the active account's browser.

Works for ANY website β€” including third-party sites that use Google Sign-In (they'll auto-SSO using the account's session). The page becomes the "current" page that google_get_page_content / google_click_element operate on.

Args: url: Absolute URL to navigate to. wait_until: "load" | "domcontentloaded" | "networkidle" (default domcontentloaded).

Inputs: url (required), wait_until. Returns: result

gv_press_keyPress KeyA

Press a single key or key chord on the active page.

Use this for things gv_fill_input can't do β€” submitting a form with Enter, tabbing between fields, dismissing a modal with Escape, selecting all with Ctrl+A, etc.

Args: key: Playwright key name β€” "Enter", "Tab", "Escape", "ArrowDown", "Backspace", "a", "1", etc. modifiers: Optional modifier keys to hold β€” ["Control"], ["Shift"], ["Control", "Shift"]. Combined as modifier+...+key. hold_ms: Hold the key down for this many ms before releasing (for long-press scenarios). 0 = tap. delay_after_ms: Pause for a randomized ~this many ms after.

Returns the pressed chord.

Inputs: key (required), hold_ms, modifiers, delay_after_ms. Returns: result

gv_read_gmailRead Gmail InboxA
Read-only

Read the Gmail inbox of the active account.

Returns recent messages as [{id, subject, sender, snippet, url, date}, ...]. Gmail's DOM changes often β€” if this returns empty, use gv_open_url to mail.google.com and google_get_page_content (with screenshot) instead.

Args: limit: Max number of messages (default 20, max 50).

Inputs: limit. Returns: result

gv_record_loginRecord Login Flow (Level 3)A
Destructive

Record a login flow for future automatic replay (Level 3).

Opens a browser, injects an action recorder, and waits for the user to complete login manually (including 2FA, captcha, etc.). After login succeeds, the recorded steps are saved to the provider's config.

Future gv_sign_in calls with the same provider will replay these steps automatically β€” pausing only for credential fields (password, OTP) and captcha that can't be replayed.

Security: password/OTP values are NEVER recorded. Only the field selectors + credential_key are saved. Store actual credentials via gv_set_credentials.

When to use:

  • Complex login flows (multi-page, custom captcha, unusual 2FA)

  • Sites where the login form is hard to describe with login_steps

  • When you want to "teach" Ghostvault how to log in once, then automate

Args: account_id: The account id to use. provider: Override the provider. Defaults to the account's provider.

Inputs: account_id (required), provider. Returns: result

gv_screenshotTake ScreenshotA
Read-only

Capture a screenshot of the current page as a PNG image (vision support).

Use this to visually understand the page when the text snapshot is ambiguous β€” e.g. to locate a button by its appearance or read a captcha.

Args: full_page: If true, capture the full scrollable page (larger image).

Inputs: full_page.

gv_scrollScroll PageA

Scroll the active page in human-like increments.

reCAPTCHA v3 and similar behavioral detectors weight scroll behavior heavily. This tool scrolls in small bursts with varied distance + reading pauses, mimicking a real user skimming the page.

Args: direction: "down" (default) or "up". amount: Roughly the number of scroll gestures (each ~300px). Default 3. humanize: Vary the scroll distance + add reading pauses between gestures (default true β€” scrolling is cheap, leave it on). delay_after_ms: Pause for a randomized ~this many ms after.

Returns the direction, amount, and whether humanize was applied.

Inputs: amount, humanize, direction, delay_after_ms. Returns: result

gv_set_credentialsStore Account CredentialsA
Destructive

Store credentials (username/password) for Level 2 form auto-fill.

Credentials are saved in the account's fingerprint bundle (encrypted at rest when encryption is enabled). Use this before calling gv_sign_in on a provider that has login_steps configured.

Args: account_id: The account id. credentials: Dict of credential key-value pairs. The keys must match the credential_key in the provider's login_steps. Example: {"username": "john", "password": "secret"}

Inputs: account_id (required), credentials (required). Returns: result

gv_setup_passwordSetup Password (Private/Public Gate)A
Destructive

Open a browser window to set a password for the private/public gate.

This is a ONE-TIME setup. After setting a password, you can mark profiles as private (google_make_private) β€” they'll be hidden until you unlock (google_unlock). Public profiles remain accessible without unlocking.

A browser window opens with a password form β€” type and confirm there. The password is stored as a salted hash (PBKDF2-SHA256, 200k iterations).

Inputs: no named parameters. Returns: result

gv_sign_inSign In to ProviderA

Open a sign-in window for the user to complete login (including 2FA).

A real browser window opens on the server's machine β€” the USER completes sign-in themselves; Ghostvault never touches the password. On success the session is saved to the account's persistent profile automatically.

First-time login from a new fingerprint usually triggers a 2FA challenge β€” this is expected. The tool blocks until login completes or times out.

Login level is auto-selected:

  • If the provider has login_steps AND credentials are available (either passed here or stored via gv_set_credentials) β†’ Level 2 auto-fill.

  • Otherwise β†’ Level 1 manual (user does everything in the visible window).

DECISION GUIDE:

  • For Google / SSO providers β†’ Level 1 manual (most reliable for 2FA/captcha).

  • For providers with login_steps β†’ store credentials first via gv_set_credentials, then sign_in.

  • Not sure what the page offers? Call gv_detect_login_options first.

Args: account_id: The account id from gv_list_accounts. provider: Override the provider for this login (e.g. "github", "facebook", or a custom provider name). Defaults to the account's provider field. credentials: Optional dict of credential values for Level 2 auto-fill (e.g. {"username": "john", "password": "secret"}). If omitted, stored credentials are loaded automatically.

Inputs: account_id (required), provider, credentials. Returns: result

gv_sign_outSign Out of ProviderA
Destructive

Sign the account out of the provider (invalidates the session server-side).

Opens the browser, navigates to the provider's sign-out URL, waits for the session to clear, then closes the browser. After this, the account must sign in again before any browser tools work.

If the provider has no logout_url configured, the browser closes and the user is told to navigate to the site's logout page manually.

Args: account_id: The account id to sign out. provider: Override the provider for this sign-out. Defaults to the account's provider field.

Inputs: account_id (required), provider. Returns: result

gv_switch_accountSwitch Active Google AccountA

Switch the active account that browser tools operate on.

The account must already be open (it becomes open after gv_sign_in). All subsequent gv_open_url / gv_read_gmail calls target the active account until you switch again.

Args: account_id: The account id to make active.

Inputs: account_id (required). Returns: result

gv_unlockUnlock Private ProfilesA

Unlock the private/public gate to access private profiles.

Two modes:

  • Pass the password directly: google_unlock({password: "..."})

  • Omit the password to open a browser window: google_unlock()

Once unlocked, private profiles are visible and accessible until you call google_logout or restart the MCP server.

Args: password: Your gate password. Omit to unlock via a browser window.

Inputs: password. Returns: result

gv_update_account_configUpdate Account Advanced ConfigA
Destructive

Update the advanced fingerprint config of an existing account.

Only the keys you pass are changed; everything else stays locked. The account's fingerprint + seeds are NOT re-rolled β€” identity stays the same, only the injection/behavioral params change.

The browser must be CLOSED when this is called; relaunch with gv_open_account to apply the new settings.

Args: account_id: The account id to update. locale, timezone, humanize, block_webrtc, block_webgl, webgl_config, fonts, addons, disable_coop, block_images: Same meanings as in gv_create_account. Pass only the ones you want to change. device_profile: Switch to a different hardware template (replaces the device_config section). Same names as in gv_create_account. device_config: Raw Camoufox config keys to merge into device_config (battery:, mediaDevices:, navigator.hardwareConcurrency, ...). Overrides values from device_profile. reset_keys: List of advanced keys to remove entirely (fall back to default). E.g. ["locale", "timezone"] to clear explicit pins. reset_device_keys: List of raw Camoufox config keys to remove from device_config. E.g. ["battery:level", "mediaDevices:webcams"].

Returns the updated keys, the new advanced + device config dicts.

Inputs: account_id (required), fonts, addons, locale, +11 more. Returns: result

gv_update_providerUpdate Custom ProviderA
Destructive

Update a custom provider's configuration. Built-in providers cannot be updated.

Pass only the fields you want to change. The provider must be closed (no active login flow) when updating.

Args: name: The provider name to update. login_url, success_url_fragments, auth_cookie_names, auth_cookie_domain, logout_url, session_probe_url, login_url_fragments, description: Same meanings as in gv_create_provider. Pass only the ones to change.

Inputs: name (required), login_url, logout_url, description, +5 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 42 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but some pairs (e.g., gv_lock_account/gv_close_account, gv_logout/gv_sign_out) could cause confusion due to overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent 'gv_' prefix and snake_case naming convention with a predictable verb_noun pattern (e.g., gv_list_accounts, gv_open_account), making navigation intuitive.

    Tool Count3/5

    With 42 tools, the server covers a broad domain but feels slightly overloaded; some tools (e.g., gv_make_private/gv_make_public) could be merged without loss of clarity.

    Completeness4/5

    The tool set comprehensively covers account lifecycle, browser automation, provider management, and security features; minor gaps exist (e.g., limited Gmail operations) but do not impede core workflows.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to securely manage Google Workspace services (Gmail, Calendar, Drive, Sheets, Contacts) with persistent multi-account OAuth. Uses OS keychain for credential storage with health monitoring and granular business rules for enterprise security.
      -
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to authenticate with websites using a real Chromium browser with anti-detection measures and human-in-the-loop support for captchas and 2FA. Features stealth browsing, human-like interactions, and persistent session storage to automate and resume login workflows.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Gives your AI agent a persistent browser identity with anti-detection, credential vault, and multi-persona support for automated web browsing, login, and signup.
      31
      5 npm
      10
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to manage multiple Gmail accounts simultaneously with built-in OAuth authentication, supporting email reading, sending, drafts, labels, and account management.
      60
      116 npm
      5
      MIT