<div align=center>

<img width="1672" height="941" alt="anima-use-google-logo" src="https://github.com/user-attachments/assets/5a51ffd2-e1e4-495a-b08f-8b24a3239db4" />

### MCP server + browser sidecar extension that lets AI agents run [Google AI Mode](https://blog.google/products/search/ai-mode-search/) searches using your **own logged-in browser session**, then return the synthesized answer and citations as an MCP tool result.

#### No headless browser, no stealth tricks, no CAPTCHA fighting. Your real browser profile does the work.

</div>

## Quickest path (5 minutes)

You need three things: the MCP server, the native-messaging host, and either the Firefox or Chromium extension. Then wire the server into your agent.

### 1. Wire the MCP server into your agent

The stable npm release is `0.1.6`. Pin it in agent configs if you want the same
server every time instead of whatever npm's `latest` tag points at later.

Claude Code:

```bash
claude mcp add ask-google -- npx anima-use-google@0.1.6
```

Other agents - add to your MCP config:

```json
{
  "mcpServers": {
    "ask-google": {
      "command": "npx",
      "args": ["anima-use-google@0.1.6"]
    }
  }
}
```

If you prefer installing straight from GitHub, pin the stable commit:

```bash
claude mcp add ask-google -- npm exec --yes --package github:animaios/anima-use-google#4311a84b580713ffd58d95dccbda8a97c635086f -- anima-use-google
```

Equivalent MCP config:

```json
{
  "mcpServers": {
    "ask-google": {
      "command": "npm",
      "args": [
        "exec",
        "--yes",
        "--package",
        "github:animaios/anima-use-google#4311a84b580713ffd58d95dccbda8a97c635086f",
        "--",
        "anima-use-google"
      ]
    }
  }
}
```

That commit is the same stable `0.1.6` release. GitHub installs run the package's
`prepare` script, so the TypeScript server is built from source before npm runs
the `anima-use-google` bin.

The MCP server talks to the sidecar over localhost; it does not bundle a browser.

### 2. Set up a browser sidecar (one-time, non-npm)

The npm tarball ships everything you need. After the first
`npx anima-use-google@0.1.6`, the files live in
`~/.npm/_npx/<hash>/node_modules/anima-use-google/`. For setup, cloning is
usually easier:

```bash
git clone https://github.com/animaios/anima-use-google
cd anima-use-google
```

#### Firefox

1. Register the native-messaging host:

   ```bash
   node native-host/install-host.cjs
   ```

   This writes the Firefox native-host registration for your OS:

   - Linux: `~/.mozilla/native-messaging-hosts/com.ask.google.json`
   - macOS: `~/Library/Application Support/Mozilla/NativeMessagingHosts/com.ask.google.json`
   - Windows: `HKCU\Software\Mozilla\NativeMessagingHosts\com.ask.google`, pointing at `%USERPROFILE%\.anima-use-google\com.ask.google.json`

2. Load the extension in Firefox:

   - Open `about:debugging#/runtime/this-firefox`.
   - Click **Load Temporary Add-on** and pick `extension/manifest.json`.
   - The host process starts on the first search.

3. Restart Firefox so the new native-messaging host is picked up.

For permanent install (loads on every FF start):

```bash
npx web-ext build --source-dir extension --overwrite-dest
# Then sign or load via about:config xpinstall.signatures.required=false (Dev/Nightly)
```

#### Chrome / Chromium / Brave

Chromium-based browsers use the `extension-chromium/` sidecar. Their native
messaging manifests require `allowed_origins`, so you need the extension id
before installing the native host.

1. Load the unpacked extension:

   - Chrome: open `chrome://extensions`.
   - Chromium: open `chromium://extensions`.
   - Brave: open `brave://extensions`.
   - Enable **Developer mode**.
   - Click **Load unpacked** and choose `extension-chromium/`.
   - Copy the generated extension id.

2. Register the native-messaging host:

   ```bash
   # Google Chrome
   node native-host/install-chrome-host.cjs --browser chrome --extension-id <extension-id>

   # Chromium
   node native-host/install-chrome-host.cjs --browser chromium --extension-id <extension-id>

   # Brave
   node native-host/install-chrome-host.cjs --browser brave --extension-id <extension-id>
   ```

   The installer writes the manifest or registry entry for your selected browser:

   - Chrome on Linux: `~/.config/google-chrome/NativeMessagingHosts/com.ask.google.json`
   - Chrome on macOS: `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.ask.google.json`
   - Chrome on Windows: `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.ask.google`
   - Chromium on Linux: `~/.config/chromium/NativeMessagingHosts/com.ask.google.json`
   - Chromium on macOS: `~/Library/Application Support/Chromium/NativeMessagingHosts/com.ask.google.json`
   - Chromium on Windows: `HKCU\Software\Chromium\NativeMessagingHosts\com.ask.google`
   - Brave on Linux: `~/.config/BraveSoftware/Brave-Browser/NativeMessagingHosts/com.ask.google.json`
   - Brave on macOS: `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/com.ask.google.json`
   - Brave on Windows: `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.ask.google`

   On Windows, the manifest JSON itself is written under
   `%USERPROFILE%\.anima-use-google\<browser>\com.ask.google.json`, and
   the registry key points the browser at that file.

3. Reload the extension so `chrome.runtime.connectNative("com.ask.google")`
   sees the manifest.

### Switching between Firefox and Chromium-based sidecars

The MCP server always connects to the first browser native host listening on
`127.0.0.1:51784`. When switching browsers during development, make sure the
old sidecar is not still owning that port.

1. Disable or unload the sidecar you are not testing:

   - Firefox: remove or disable the temporary add-on from
     `about:debugging#/runtime/this-firefox`.
   - Chrome/Chromium/Brave: disable or remove the unpacked extension from
     `chrome://extensions`, `chromium://extensions`, or `brave://extensions`.

2. Stop any stale native host:

   ```bash
   ps -ef | rg '[n]ative-host/host\.js'
   kill <pid>
   ```

3. Register the host manifest for the browser you want:

   ```bash
   # Firefox
   node native-host/install-host.cjs

   # Google Chrome
   node native-host/install-chrome-host.cjs --browser chrome --extension-id <chrome-extension-id>

   # Chromium
   node native-host/install-chrome-host.cjs --browser chromium --extension-id <chrome-extension-id>

   # Brave
   node native-host/install-chrome-host.cjs --browser brave --extension-id <brave-extension-id>
   ```

4. Reload the chosen browser extension so it reconnects to native messaging.

5. Confirm which browser owns the host before running an E2E test:

   ```bash
   ps -ef | rg '[n]ative-host/host\.js|[b]rave|[c]hrome|[c]hromium|[f]irefox'
   ss -ltnp 'sport = :51784'
   ```

   For Chromium-based browsers, the host command should include an origin like
   `chrome-extension://<extension-id>/`. For Firefox, it is normally launched
   without that Chrome extension-origin argument.

### 3. Use it

Ask your agent normally:

> Search Google AI Mode for: Next.js 15 App Router best practices

The agent calls `ask_google`, your browser sidecar opens the `udm=50` search in your profile, the extension parses the AI answer with inline `[1][2]` citations, and the agent gets a grounded markdown response.

## anima-use-google-cli

The `anima-use-google-cli` binary searches Google AI Mode directly through the native host on `127.0.0.1:51784`. It does **not** spawn the MCP server (`dist/index.js`) and has zero dependency on the `@modelcontextprotocol/sdk` — per invocation it runs as a single pure-Node process.

```
anima-use-google-cli <query>
  ├─ toGoogleAiModeQuery(query)         appends "answer in English" unless already requested
  ├─ new NativeMessagingBridge()        raw TCP to 127.0.0.1:51784 (4-byte LE prefix + JSON)
  ├─ bridge.search(query, timeoutMs)    framed request to host.js → extension → Google AI Mode
  ├─ parseAiResponse(html, citations)  cheerio + turndown → grounded markdown
  └─ stdout: markdown | --json | --raw ; stderr: errors ; exit 0/1/2
```

Designed for harnesses and people who don't want the MCP client interface. The CLI runs on Node 20+ with no new packages — cross-platform by construction (`bridge.dispose()` always runs in a `finally`, no lingering socket or child process).

```bash
# Positional (space-joined)
anima-use-google-cli <query>

# --query flag form is equivalent to positional
anima-use-google-cli --query "your query"

# Piped input
echo "your query" | anima-use-google-cli --stdin

# Or omit the flag — piped stdin is auto-detected when no positional or --query is given
```

Output modes:

- **Default** — parsed markdown answer (inline `[n]` citations + `## Sources` section) goes to **stdout**; errors go to **stderr**, exit 1.
- **`--json`** — a single JSON document to **stdout** and nothing else on any stream. Success: `{"ok":true,"markdown":"...","citations":[...]}` (exit 0). Any failure: `{"ok":false,"error":"..."}` (exit 1). The `citations` field is always present — an empty array when there are none.
- **`--raw`** — the verbatim host frame (`{"requestId",ok,"html","citations",error}`) to **stdout**; no `parseAiResponse` applied (the `html` is the raw host HTML containing `[CITE-N]` markers). Exit 0 on success, 1 on failure; nothing on stderr.
- **Precedence** — when `--json` and `--raw` are both passed, `--raw` wins (consistent on success and failure paths).

The `status` subcommand probes reachability without sending a search:

```bash
anima-use-google-cli status   # --json and --raw are accepted but produce the same schema
# reachable → {"ok":true,"host":"127.0.0.1","port":51784,"reachable":true} (exit 0)
# unreachable → {"ok":false,"host":"127.0.0.1","port":51784,"reachable":false} (exit 1)
# stderr is always empty on the status path
```

Environment (honored by the CLI and by the bridge it loads):

| Variable | Default | Effect |
|---|---|---|
| `GOOGLE_AI_HOST_HOST` | `127.0.0.1` | TCP host for search + status |
| `GOOGLE_AI_HOST_PORT` | `51784` | TCP port for search + status |
| `GOOGLE_AI_TIMEOUT_MS` | `60000` | Default per-request timeout in ms |
| `GOOGLE_AI_BRIDGE_GRACE_MS` | `30000` | Grace period on top of the timeout (for the bridge's rejection) |

`--timeout-ms <ms>` (or the alias `--timeout <ms>`) overrides `GOOGLE_AI_TIMEOUT_MS` for a single invocation.

Exit codes:

- **0** success
- **1** search/host error, including timeout (`default` → stderr; `--json`/`--raw` → structured stdout)
- **2** usage error (`--help`, bad args, empty query, `--stdin` on TTY) — error message on stderr, no network contact

## How it works

```
Agent (stdio) <---> MCP server <---> localhost TCP <---> host.js
       <---> browser native port <---> background script
       <---> opens google.com/search?udm=50&q=...
       <---> content.js parses AI answer + sources
       <---> response back along the same chain
```

Your logged-in Google cookies are reused because the tab is opened in your own browser profile - if you have AI Mode enabled, it works; CAPTCHAs don't trigger (real user profile, no stealth games).

The multilanguage completion detection (SVG thumbs-up → aria-label → text markers → 40s fallback) and SERPO-style citation parsing are ported from the Battle-tested [google-ai-mode-mcp](https://github.com/PleasePrompto/google-ai-mode-mcp).

## Developers

<img width="256" height="384" alt="AnimAIOS mascot" src="https://github.com/user-attachments/assets/8df6553c-e975-4ac4-b32c-fc73cdf0eebd" />

Want to hack on the MCP server or build from source:

```bash
npm install
npm run build     # tsc -> dist/
npm test          # node:test regression suite
```