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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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).

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).

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).

List the visible links on the current page.

Returns [{text, href}, ...]. Use this to choose where to navigate next.

Args: limit: Max number of links to return (default 50, max 100).

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.

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.

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.

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.

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).

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).

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.

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).

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.

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.

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.

Mark a profile as public (accessible without unlocking).

Args: account_id: The account id to make public.

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.

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.

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

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

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.

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

Args: name: The provider name to delete.

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.

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.

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"}

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

Args: account_id: The account id.

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}.

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.

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.

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.