Skip to content

Connect your agent

Ghostvault is an MCP server, so any MCP-compatible client can connect. This page has copy-paste config for the most common ones: Claude Desktop, Cursor, ZCode, and Cline.

Installer already did this?

If you ran the one-line installer, it already wrote the config for Claude Desktop and Cursor if they were detected. Just restart those apps and you can skip ahead to First sign-in. The snippets below are for connecting a different client, or for a manual install.

How the connection works

Ghostvault uses the stdio transport by default. Your AI client spawns Ghostvault as a subprocess — it runs python -m ghostvault, talks to it over stdin/stdout using the MCP protocol, and tears it down when the client quits. There's no daemon to start or port to manage.

Client (Claude Desktop / Cursor / ...) launches →
  python -m ghostvault   (Ghostvault MCP server, running as a subprocess)
        │
        ▼
  MCP protocol over stdio

Every client config boils down to three things:

  1. command — an absolute path to a Python interpreter that has Ghostvault installed.
  2. args — ["-m", "ghostvault"] (always the same).
  3. env (optional) — any GHOSTVAULT_* variables you want to set. See Configuration basics.

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:

  • macOS/Linux: ~/.ghostvault-app/.venv/bin/python
  • Windows: %USERPROFILE%\.ghostvault-app\.venv\Scripts\python.exe

Run which python (macOS/Linux) or where python (Windows) in the venv where you installed Ghostvault, or use a known path like /opt/homebrew/bin/python3, /usr/bin/python3, etc.

Find your Python path

Before editing any config, grab the absolute path to the Python that has Ghostvault installed. You'll paste it into every client config below.

ls ~/.ghostvault-app/.venv/bin/python

Test-Path "$env:USERPROFILE\.ghostvault-app\.venv\Scripts\python.exe"

Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ghostvault": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "ghostvault"],
      "env": {
        "GHOSTVAULT_HEADLESS": "false"
      }
    }
  }
}

Replace /absolute/path/to/python with the venv Python from the step above. GHOSTVAULT_HEADLESS=false opens a visible browser window so you can complete login + 2FA — keep it for first sign-in.

Restart Claude Desktop. Click the tools/hammer icon to confirm gv_* tools appear.

Cursor

Edit Cursor's MCP config at ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

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

Restart Cursor. Verify under Settings → MCP, where Ghostvault should show as connected with its gv_* tools listed.

ZCode

ZCode nests MCP servers under mcp.servers. Edit the workspace config at <repo>/.zcode/config.json, or the user config at ~/.zcode/cli/config.json:

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

ZCode uses a nested shape

Note the extra mcp.servers nesting — ZCode's config is not flat like Claude Desktop's. ZCode's tools will appear prefixed with mcp__ghostvault__ (e.g. mcp__ghostvault__gv_list_accounts).

Cline (VS Code)

Cline stores MCP config at ~/.cline/data/settings/cline_mcp_settings.json. Cline adds two extra fields — keep them:

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

disabled: false keeps the server on; autoApprove: [] means Cline asks before each tool call (add tool names to auto-approve them).

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.

The clients disagree on the exact JSON shape (some nest under mcpServers, some under servers, some under mcp.servers) — see examples/README.md in the repo for the full shape cheat-sheet and ready-to-copy files for VS Code, Continue.dev, and Claude Code (CLI).

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 with claude mcp list. Scopes: -s user (all projects), -s project (shared via .mcp.json), -s local (default).

Hermes Agent (Nous Research)

Hermes Agent supports MCP servers via an mcpServers config block — same shape as Claude Desktop. See hermes_config.json for a ready-to-copy file.

Hermes env security

Hermes limits which environment variables are passed to subprocesses. Make sure GHOSTVAULT_* vars are explicitly listed in the env block (they are in the example file).

OpenClaw

OpenClaw supports MCP servers via openclaw.json or the openclaw mcp add CLI command. See openclaw_config.json for a ready-to-copy file.

# CLI alternative:
openclaw mcp add ghostvault -- /absolute/path/to/python -m ghostvault

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 (macOS/Linux) or Test-Path (Windows) should succeed.
  • 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.

Remote / HTTP transport (advanced)

For a remote setup (e.g. Ghostvault on a server, client on your laptop), serve it over HTTP instead of stdio:

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 — and secure it). This is covered in depth in Remote (HTTP transport).

Next steps