<div align=center>

anima-use-google

MCP server + browser sidecar extension that lets AI agents run Google AI Mode searches using your own logged-in browser session, then return the synthesized answer and citations as an MCP tool result.

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

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

Claude Code:

claude mcp add google-ai-search -- npx anima-use-google

Other agents - add to your MCP config:

{
  "mcpServers": {
    "google-ai-search": {
      "command": "npx",
      "args": ["anima-use-google"]
    }
  }
}

If you do not want your agent to follow npm's moving latest tag, pin the MCP server to a GitHub commit instead:

claude mcp add google-ai-search -- npm exec --yes --package github:animaios/anima-use-google#<commit-sha> -- anima-use-google

Equivalent MCP config:

{
  "mcpServers": {
    "google-ai-search": {
      "command": "npm",
      "args": [
        "exec",
        "--yes",
        "--package",
        "github:animaios/anima-use-google#<commit-sha>",
        "--",
        "anima-use-google"
      ]
    }
  }
}

Use a full commit SHA for reproducibility. 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, the files live in ~/.npm/_npx/<hash>/node_modules/anima-use-google/ - easiest to clone:

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

Firefox

1. Register the native-messaging host:

   node native-host/install-host.cjs
   

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

   • Linux: ~/.mozilla/native-messaging-hosts/com.google.ai.search.json
   • macOS: ~/Library/Application Support/Mozilla/NativeMessagingHosts/com.google.ai.search.json
   • Windows: HKCU\Software\Mozilla\NativeMessagingHosts\com.google.ai.search, pointing at %USERPROFILE%\.anima-use-google\com.google.ai.search.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):

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:

   # 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.google.ai.search.json
   • Chrome on macOS: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.google.ai.search.json
   • Chrome on Windows: HKCU\Software\Google\Chrome\NativeMessagingHosts\com.google.ai.search
   • Chromium on Linux: ~/.config/chromium/NativeMessagingHosts/com.google.ai.search.json
   • Chromium on macOS: ~/Library/Application Support/Chromium/NativeMessagingHosts/com.google.ai.search.json
   • Chromium on Windows: HKCU\Software\Chromium\NativeMessagingHosts\com.google.ai.search
   • Brave on Linux: ~/.config/BraveSoftware/Brave-Browser/NativeMessagingHosts/com.google.ai.search.json
   • Brave on macOS: ~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/com.google.ai.search.json
   • Brave on Windows: HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.google.ai.search

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

3. Reload the extension so chrome.runtime.connectNative("com.google.ai.search") 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:

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

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

   # 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:

   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 search_google_ai, 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.

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.

Developers

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

npm install
npm run build     # tsc -> dist/
npm test          # node:test regression suite
npm link          # then `anima-use-google` on PATH

Project layout:

• src/ + dist/ - TypeScript MCP server publishing as anima-use-google.
• native-host/ - host.js bridges browser native messaging <-> localhost TCP; install-host.cjs writes the Firefox manifest; install-chrome-host.cjs writes the Chrome/Chromium/Brave manifest.
• extension/ - Firefox MV3 sidecar.
• extension-chromium/ - Chrome/Chromium/Brave MV3 sidecar using a service worker background.
• Selector constants live in each extension's src/selectors.js - update both if Google's AI Mode DOM shifts.

Tuning

Cutoff markers (end-of-answer disclaimers, language-aware) and citation selectors are in extension/src/selectors.js and extension-chromium/src/selectors.js. If extraction fails on your locale, add your language's markers there.

License

unLICENSE. See LICENSE.