Skip to content
Back to search

google-ai-mode-mcp

MCP server for free Google AI Mode search with citations. Query optimization, CAPTCHA handling, multi-agent support. Works with Claude Code, Cursor, Cline, Windsurf.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pleaseprompto--google-ai-mode-mcp/badge.svg)](/listings/pleaseprompto--google-ai-mode-mcp)

HTML

<a href="/listings/pleaseprompto--google-ai-mode-mcp"><img src="/api/listings/pleaseprompto--google-ai-mode-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Works with any MCP-compatible code agent. Choose your setup:

**Claude Code:**

claude mcp add google-ai-search npx google-ai-mode-mcp@latest

**Codex:**

codex mcp add google-ai-search -- npx google-ai-mode-mcp@latest

**Linux/WSL users on Codex:** If you get a "Missing X-Server" error when trying to show the browser for CAPTCHA solving, use xvfb-run:

{
  "mcpServers": {
    "google-ai-search": {
      "command": "xvfb-run",
      "args": ["-a", "npx", "google-ai-mode-mcp@latest"]
    }
  }
}

Install xvfb if needed: `sudo apt-get install xvfb`

**Cline:**

cline mcp add google-ai-search -- npx google-ai-mode-mcp@latest

**Gemini:**

gemini mcp add google-ai-mode npx -y google-ai-mode-mcp@latest --scope user

**VS Code:**

code --add-mcp '{"name":"google-ai-search","command":"npx","args":["google-ai-mode-mcp@latest"]}'

**Cursor, Windsurf, Zed, or other MCP clients:**

Add to your MCP config file:

{
  "mcpServers": {
    "google-ai-search": {
      "command": "npx",
      "args": ["google-ai-mode-mcp@latest"]
    }
  }
}

Cursor uses `~/.cursor/mcp.json`, Windsurf and Zed have their own settings files. Check your agent's documentation for the config location

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 459 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > [!WARNING]
  2. > **This project is no longer maintained.** As of September 2026 the repository is archived: no updates, bug fixes or support. The npm package will not receive further releases. It may stop working when the upstream services change. Feel free to fork.
  3. <div align="center">
  4. # Google AI Mode MCP Server
  5. ### **Supercharge Any LLM's Web Research with Google AI Mode**
  6. **For: All MCP-compatible LLMs** (Claude, Cursor, Cline, Windsurf, Zed, etc.)
  7. Transform your LLM's online research capabilities by connecting it directly to Google's AI Mode—getting AI-synthesized answers from 100+ sources instead of scattered search results.
  8. [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
  9. [![MCP](https://img.shields.io/badge/MCP-2026-green.svg)](https://modelcontextprotocol.io/)
  10. [![npm](https://img.shields.io/npm/v/google-ai-mode-mcp.svg)](https://www.npmjs.com/package/google-ai-mode-mcp)
  11. [![Claude Code Skill](https://img.shields.io/badge/Claude_Code-Skill_Version-purple.svg)](https://github.com/PleasePrompto/google-ai-mode-skill)
  12. [![GitHub](https://img.shields.io/github/stars/PleasePrompto/google-ai-mode-mcp?style=social)](https://github.com/PleasePrompto/google-ai-mode-mcp)
  13. ### Why This Matters
  14. Most built-in web research is mediocre. This MCP server gives **any LLM professional-grade research** by tapping into Google's AI Mode—the same technology that synthesizes information from dozens of websites into one cited answer.
  15. **Example Use Cases:**
  16. ```
  17. "Next.js 15 App Router best practices 2026 with server components examples"
  18. → AI-synthesized coding guide with inline citations [1][2][3]
  19. "Compare PostgreSQL vs MySQL JSON performance 2026, include benchmarks"
  20. → Technical comparison table with real-world data
  21. "Find the latest EU AI regulations 2026 and their impact on startups"
  22. → Legal overview with official government sources
  23. "Best noise-cancelling headphones under €300, compare Sony vs Bose"
  24. → Product comparison with reviews and specs
  25. "Intermittent fasting protocols 2026, include recent scientific studies"
  26. → Health guide with medical research citations
  27. ```
  28. **Result:** Research on **ANY topic**—coding, tech comparisons, regulations, product reviews, health, finance, travel. Curated answers with sources. Saves tokens. Superior to generic web search.
  29. [Installation](#installation) • [Quick Start](#quick-start) • [How It Works](#how-it-works) • [Examples](#example-use-case) • [Claude Code Skill](https://github.com/PleasePrompto/google-ai-mode-skill) • [FAQ](#faq)
  30. </div>
  31. ---
  32. ## 📋 Last Updates (2026-01-08)
  33. **v2.0 - Multi-Language & Detection Overhaul**
  34. ✅ **4-Stage Completion Detection** - SVG thumbs-up → aria-label → text → 40s timeout
  35. ✅ **Multi-Language Support** - Works in DE/EN/NL/ES/FR/IT browser locales
  36. ✅ **87% Faster** - Average 4s detection (was 2s fixed wait)
  37. ✅ **AI Mode Availability Check** - Detects region restrictions with proxy suggestion
  38. ✅ **17 Citation Selectors** - Language-agnostic fallback chain
  39. ✅ **15 Cutoff Markers** - Cleaner content extraction across languages
  40. <details>
  41. <summary>📖 Show previous updates</summary>
  42. **v1.5** - Persistent browser context, CAPTCHA handling improvements
  43. **v1.0** - Initial MCP server release
  44. </details>
  45. ---
  46. ## What This Is
  47. An MCP server that connects your code agent (Claude, Cursor, Cline, etc.) to **Google AI Mode**—Google's AI-powered search that synthesizes information from dozens of web sources into a single, cited answer.
  48. Instead of your agent reading page after page, Google does the heavy lifting. Your agent gets one clean, structured response with inline citations.
  49. **The advantage:** Free, token-efficient research with grounded sources.
  50. ---
  51. ## How It Works
  52. ```
  53. Your agent asks a question
  54. ↓
  55. Server launches stealth browser
  56. ↓
  57. Google AI Mode searches & synthesizes dozens of sources
  58. ↓
  59. Server extracts AI answer + citations
  60. ↓
  61. Converts to clean Markdown with [1][2][3] references
  62. ↓
  63. Your agent receives final answer (optionally saved to .md file)
  64. ```
  65. **The key difference:**
  66. Traditional web research:
  67. - Agent searches Google → gets 10 links
  68. - Agent reads 5-10 full pages → thousands of tokens consumed
  69. - Agent synthesizes manually → risks missing details or hallucinating
  70. - You pay for all those tokens
  71. With this server:
  72. - Google AI Mode searches + synthesizes → one request
  73. - Your agent receives one clean, cited answer → minimal tokens
  74. - Google's sources are preserved → verifiable, grounded
  75. - It's free (uses public Google Search)
  76. ---
  77. ## Why This Matters
  78. Google AI Mode (the `udm=50` parameter) makes Google search work like a research assistant. It:
  79. - Reads and analyzes dozens of websites automatically
  80. - Synthesizes findings into structured answers
  81. - Cites every claim with source links
  82. - Handles follow-up context across queries
  83. Your agent gets the benefits without doing the work—or burning the tokens
  84. ---
  85. ## Installation
  86. Works with any MCP-compatible code agent. Choose your setup:
  87. **Claude Code:**
  88. ```bash
  89. claude mcp add google-ai-search npx google-ai-mode-mcp@latest
  90. ```
  91. **Codex:**
  92. ```bash
  93. codex mcp add google-ai-search -- npx google-ai-mode-mcp@latest
  94. ```
  95. **Linux/WSL users on Codex:** If you get a "Missing X-Server" error when trying to show the browser for CAPTCHA solving, use xvfb-run:
  96. ```json
  97. {
  98. "mcpServers": {
  99. "google-ai-search": {
  100. "command": "xvfb-run",
  101. "args": ["-a", "npx", "google-ai-mode-mcp@latest"]
  102. }
  103. }
  104. }
  105. ```
  106. Install xvfb if needed: `sudo apt-get install xvfb`
  107. **Cline:**
  108. ```bash
  109. cline mcp add google-ai-search -- npx google-ai-mode-mcp@latest
  110. ```
  111. **Gemini:**
  112. ```bash
  113. gemini mcp add google-ai-mode npx -y google-ai-mode-mcp@latest --scope user
  114. ```
  115. **VS Code:**
  116. ```bash
  117. code --add-mcp '{"name":"google-ai-search","command":"npx","args":["google-ai-mode-mcp@latest"]}'
  118. ```
  119. **Cursor, Windsurf, Zed, or other MCP clients:**
  120. Add to your MCP config file:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "google-ai-search": {
  125. "command": "npx",
  126. "args": ["google-ai-mode-mcp@latest"]
  127. }
  128. }
  129. }
  130. ```
  131. Cursor uses `~/.cursor/mcp.json`, Windsurf and Zed have their own settings files. Check your agent's documentation for the config location
  132. ---
  133. ## Quick Start
  134. Ask your agent naturally:
  135. ```
  136. "Search Google AI Mode for: Next.js 15 App Router best practices"
  137. ```
  138. ```
  139. "What are the new features in Astro 4.0?"
  140. ```
  141. ```
  142. "Research React Server Components and save the results"
  143. ```
  144. The agent will automatically use the MCP server to query Google AI Mode and return a clean, cited answer.
  145. **To save results to a file:**
  146. ```
  147. "Search for TypeScript 5.4 features and save it"
  148. ```
  149. Files are saved to platform-specific locations:
  150. - **Linux**: `~/.local/share/google-ai-mode-mcp/results/`
  151. - **macOS**: `~/Library/Application Support/google-ai-mode-mcp/results/`
  152. - **Windows**: `%LOCALAPPDATA%\google-ai-mode-mcp\results\`
  153. Filenames: `2026-01-04_15-30-45_typescript_5_4.md`
  154. ---
  155. ## First Run: CAPTCHA Handling
  156. On your first query, Google may show a CAPTCHA to verify you're human. This is normal when the browser profile is created.
  157. **If you see a CAPTCHA error:**
  158. 1. Ask your agent: "Switch to visible mode" or "Turn off headless mode"
  159. 2. The browser will open visibly
  160. 3. Solve the CAPTCHA manually
  161. 4. The server detects the solution automatically and continues
  162. 5. Next queries will be headless again
  163. After the first CAPTCHA, searches typically run smoothly. The server uses stealth techniques and a persistent browser profile to minimize future CAPTCHAs
  164. ---
  165. ## Troubleshooting
  166. **Repeated CAPTCHAs:**
  167. If Google keeps showing CAPTCHAs:
  168. - Tell your agent: "Use visible browser for this search"
  169. - Add 10-30 second delays between searches
  170. - The server automatically restarts after 3 consecutive CAPTCHAs
  171. **Browser won't launch:**
  172. Clear the browser profile:
  173. ```bash
  174. # Linux/macOS
  175. rm -rf ~/.local/share/google-ai-mode-mcp/chrome_profile
  176. # Windows
  177. rmdir /s "%LOCALAPPDATA%\google-ai-mode-mcp\chrome_profile"
  178. ```
  179. **Wrong language results:**
  180. The server forces English results. If you still get wrong languages, clear the profile (see above).
  181. **Missing citations:**
  182. Update to the latest version:
  183. ```bash
  184. npm update -g google-ai-mode-mcp
  185. ```
  186. ---
  187. ## Configuration (Optional)
  188. The server works out of the box. Advanced users can customize via environment variables:
  189. ```bash
  190. # Browser settings
  191. export GOOGLE_AI_HEADLESS=true # Run browser invisibly
  192. export GOOGLE_AI_STEALTH_ENABLED=true # Use anti-detection techniques
  193. # Timeouts
  194. export GOOGLE_AI_RESPONSE_TIMEOUT=30000 # 30 seconds to get AI response
  195. export GOOGLE_AI_CAPTCHA_TIMEOUT=300000 # 5 minutes to solve CAPTCHA
  196. # CAPTCHA handling
  197. export GOOGLE_AI_CAPTCHA_POLL_INTERVAL=3000 # Check every 3 seconds
  198. export GOOGLE_AI_CAPTCHA_MAX_CONSECUTIVE=3 # Restart after 3 CAPTCHAs
  199. export GOOGLE_AI_CAPTCHA_COOLDOWN_MS=30000 # 30 second cooldown
  200. ```
  201. See `.env.example` for all options.
  202. ---
  203. ## Tool Reference
  204. The server exposes one tool: `search_ai`
  205. **Parameters:**
  206. - `query` (required) - Your search question
  207. - `headless` (optional) - Run browser invisibly (default: `true`)
  208. - `timeout_ms` (optional) - Request timeout in milliseconds (default: `120000`)
  209. - `save_to_file` (optional) - Save result to .md file (default: `false`)
  210. - `filename` (optional) - Custom filename without `.md` extension
  211. **Returns:**
  212. ```json
  213. {
  214. "success": true,
  215. "markdown": "# AI response with citations [1][2]\n\nSources:\n[1] [Title](url)",
  216. "sources": [
  217. { "title": "Source Title", "url": "https://example.com", "domain": "example.com" }
  218. ],
  219. "query": "Your query",
  220. "savedTo": "/path/to/results/file.md"
  221. }
  222. ```
  223. **Usage examples:**
  224. Basic search:
  225. ```javascript
  226. { "query": "Rust async patterns 2026" }
  227. ```
  228. Save to file:
  229. ```javascript
  230. { "query": "Next.js 15 features", "save_to_file": true, "filename": "nextjs-15-guide" }
  231. ```
  232. Visible browser (for CAPTCHA or debugging):
  233. ```javascript
  234. { "query": "PostgreSQL optimization", "headless": false }
  235. ```
  236. ---
  237. ## Example Use Case
  238. You need to implement OAuth2 in a framework you've never used before.
  239. **Traditional approach:**
  240. - Your agent searches Google, gets 10 links
  241. - Reads multiple documentation pages and blog posts
  242. - Consumes thousands of tokens
  243. - May miss important details or synthesize incorrectly
  244. **With this server:**
  245. ```
  246. "Search Google AI Mode for: Hono OAuth2 implementation guide"
  247. ```
  248. - Google reads and synthesizes sources automatically
  249. - Your agent gets one structured answer with code examples and citations
  250. - Minimal token usage
  251. - Sources are linked for verification
  252. The agent can then use this grounded information to write the actual implementation.
  253. ---
  254. ## FAQ
  255. **Does this work with my code agent?**
  256. Yes. Any MCP-compatible client: Claude Code, Cursor, Codex, Cline, Windsurf, Zed, VS Code MCP, etc.
  257. **Is it free?**
  258. Yes. The server is open source, and it uses public Google Search. No API keys or subscriptions needed.
  259. **How accurate are the results?**
  260. Results come from Google's AI Mode, which cites sources for every claim. Always verify critical details via the linked sources.
  261. **What about privacy?**
  262. Everything runs locally on your machine. The browser profile stays on your computer. No credentials or external services required beyond Google Search.
  263. **Can I see the browser while it works?**
  264. Yes. Set `headless: false` in the tool call, or ask your agent to use visible mode.
  265. **Why not just use regular web search?**
  266. Regular search returns links. Your agent then reads 5-10 pages, consuming thousands of tokens. This server has Google do the synthesis, so your agent gets one clean answer for minimal token cost.
  267. ---
  268. ## Tips for Better Results
  269. **Be specific with your queries:**
  270. Instead of: "React hooks"
  271. Try: "React hooks best practices 2026 (useState, useEffect, custom hooks)"
  272. **Include version numbers:**
  273. Instead of: "Next.js features"
  274. Try: "Next.js 15 new features and breaking changes"
  275. **Request structured output:**
  276. "Compare PostgreSQL vs MySQL 2026 with a performance comparison table"
  277. **Ask for examples:**
  278. "Show me TypeScript discriminated union examples with type narrowing"
  279. ---
  280. ## Development
  281. Want to contribute or run from source?
  282. ```bash
  283. git clone https://github.com/PleasePrompto/google-ai-mode-mcp.git
  284. cd google-ai-mode-mcp
  285. npm install
  286. npm run build
  287. # Development with auto-reload
  288. npm run dev
  289. # Watch mode for continuous building
  290. npm run watch
  291. ```
  292. ---
  293. ## Important Notes
  294. **CAPTCHA handling:**
  295. Google may show a CAPTCHA on first use or if you search very frequently. When this happens, ask your agent to show the browser ("switch to visible mode"). Once you solve the CAPTCHA manually, you're usually good to go for future searches.
  296. **Responsible use:**
  297. This tool automates browser interactions with Google Search. Use it responsibly and be mindful of Google's Terms of Service. Add delays between heavy search sessions if needed.
  298. **Verification:**
  299. While results come from Google's AI Mode with source citations, always verify critical information via the linked sources. This is a research tool, not a source of truth.
  300. ---
  301. ## Contributing
  302. Found an issue or want to contribute?
  303. - Report bugs: [GitHub Issues](https://github.com/PleasePrompto/google-ai-mode-mcp/issues)
  304. - Pull requests: Welcome
  305. - Contact: [github@geromedexheimer.de](mailto:github@geromedexheimer.de)
  306. ---
  307. ## License
  308. MIT License - see LICENSE file for details
  309. ---
  310. ## Claude Code Users
  311. Using Claude Code? There's a lightweight **skill-only version** of this server that integrates directly into your Claude Code workflow without requiring a separate MCP server installation.
  312. **Check it out:** [google-ai-mode-skill](https://github.com/PleasePrompto/google-ai-mode-skill)
  313. The skill version is perfect if you want the same Google AI Mode functionality with even simpler setup for Claude Code.
  314. ---
  315. **Built by [Gérôme Dexheimer](mailto:github@geromedexheimer.de)**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.