Ask Google MCP Server

ask-google-mcp is a stdio MCP server that exposes a single tool, ask_google.

That tool sends a question to Gemini with Google Search grounding enabled, then returns:

• a synthesized answer
• appended source links
• appended search queries Gemini performed

This is for agent workflows that need current web information inside an MCP client such as Claude Code.

What It Does

ask_google is useful when the agent needs information that should not be answered from stale training data alone, for example:

• latest versions, releases, and changelogs
• current docs, standards, or API changes
• comparisons between current products or libraries
• recent announcements or status checks
• short web research tasks with citations

The server is intentionally narrow:

• one MCP tool: ask_google
• stdio transport only
• no web UI
• no HTTP server

Recommended Setup: Claude Code User Scope

I checked the local Claude Code CLI help.

claude mcp --help shows that add supports scopes local, user, and project, and claude mcp add --help shows the default scope is local.

If you want this available across all projects, use --scope user.

Option 1: Install from npm globally

npm install -g @gpriday/ask-google-mcp

Then add it to Claude Code at user scope and set the API key directly in the MCP config:

claude mcp add --scope user -e GOOGLE_API_KEY=your_api_key_here ask-google -- ask-google-mcp

Verify it:

claude mcp get ask-google
claude mcp list

Option 2: Use a local checkout

This is better for development, not for normal usage.

git clone https://github.com/gpriday/ask-google-mcp.git
cd ask-google-mcp
npm install

Then register that checkout with Claude Code:

claude mcp add --scope user -e GOOGLE_API_KEY=your_api_key_here ask-google -- node /absolute/path/to/ask-google-mcp/src/index.js

Requirements

• Node.js >=20
• A Google AI Studio API key with Gemini access

Get an API key here:

• https://aistudio.google.com/apikey

How Configuration Actually Works

The server loads environment variables in this order:

1. process.cwd()/.env
2. ~/.env
3. existing process environment variables

That means:

• it does read ~/.env
• it does not read a fixed repository root unless the server process is started from that directory
• for Claude Code, passing the API key with claude mcp add -e GOOGLE_API_KEY=... is the clearest and most reliable setup

Minimum required variable for live tool calls:

GOOGLE_API_KEY=your_api_key_here

Optional variables:

ASK_GOOGLE_MAX_RETRIES=2          # 0 disables retries entirely
ASK_GOOGLE_INITIAL_RETRY_DELAY_MS=1000

# Size caps
ASK_GOOGLE_MAX_QUESTION_LENGTH=64000
ASK_GOOGLE_MAX_RESPONSE_CHARS=2000000
ASK_GOOGLE_MAX_OUTPUT_TOKENS=32768

# Timeouts (milliseconds)
ASK_GOOGLE_TIMEOUT_MS=120000      # hard ceiling per attempt
ASK_GOOGLE_TTFT_MS=45000          # abort if no first token arrives in this window
ASK_GOOGLE_INACTIVITY_MS=25000    # abort if the stream goes silent mid-response
ASK_GOOGLE_OVERALL_BUDGET_MS=420000

# Gemini 3.8 Flash thinking level: LOW|MEDIUM|HIGH (default LOW)
ASK_GOOGLE_THINKING_LEVEL=LOW

# Override the model id, only needed if Google renames it
# ASK_GOOGLE_MODEL=gemini-3.8-flash

Runtime Behavior

• The server starts even if GOOGLE_API_KEY is missing.
• MCP clients can still initialize and list tools without the key.
• The ask_google tool itself returns an [AUTH_ERROR] if called without a key.
• Each attempt is capped by ASK_GOOGLE_TIMEOUT_MS, with the whole call bounded by ASK_GOOGLE_OVERALL_BUDGET_MS.
• Retries are enabled for retryable upstream failures.

Tool Reference

Tool name

ask_google

Inputs

• question - required string (also accepted as query alias; do not set both)

That is the entire input surface. There is no model parameter: every request goes to gemini-3.8-flash.

Model

The server always calls gemini-3.8-flash. There are no tiers, no model argument, and no routing step — one model handles both quick lookups and multi-source research briefs.

Set ASK_GOOGLE_MODEL if Google renames the model id and you need to point at the new one.

Breaking change in 0.11.0. Earlier versions exposed a model parameter (auto, flash, flash-lite, plus a legacy pro alias) and an auto-routing classifier. All of that is gone. A model argument sent by an older caller is ignored rather than rejected, so existing integrations keep working — they just always get gemini-3.8-flash.

Example Tool Calls

Basic current-information query

{
  "name": "ask_google",
  "arguments": {
    "question": "Find the current Node.js LTS version and its release date"
  }
}

Research-style comparison

{
  "name": "ask_google",
  "arguments": {
    "question": "React 19 vs React 18: current migration risks, breaking changes, and official upgrade guidance"
  }
}

What The Tool Returns

The tool returns text content that includes:

• Gemini's answer
• a Sources section appended by the server
• a Search queries performed section appended by the server when available

CLI Usage

If you installed the package globally:

ask-google-mcp

If you are running from a local checkout:

npm start

CLI flags:

ask-google-mcp --help
ask-google-mcp --version

Environment Validation

For local development, validate configuration with:

npm run check-env

That script checks:

• whether a local .env or ~/.env exists
• whether GOOGLE_API_KEY looks present and non-placeholder
• Node.js version compatibility
• optional runtime settings like timeout flags

Claude Desktop

Claude Code is the primary recommended workflow, but Claude Desktop can also run the server.

Global install example:

{
  "mcpServers": {
    "ask-google": {
      "command": "ask-google-mcp",
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local checkout example:

{
  "mcpServers": {
    "ask-google": {
      "command": "node",
      "args": ["/absolute/path/to/ask-google-mcp/src/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development

Project structure:

src/
  ask-google.js
  config.js
  errors.js
  index.js
  prompt.js
  retry.js
  sanitize.js
  server.js
  system-prompt.txt
  tool.js
scripts/
  check-env.js
test/
  integration/
  support/
  unit/

Scripts:

• npm start - start the MCP server
• npm test - run unit tests
• npm run test:integration - run live integration tests when enabled
• npm run test:all - run both suites
• npm run dev - run with node --watch
• npm run check-env - validate environment config

Live integration tests only run when both are set:

RUN_LIVE_TESTS=1
GOOGLE_API_KEY=your_api_key_here

Error Categories

Tool failures are surfaced as MCP errors with categorized messages:

• [AUTH_ERROR] - missing or invalid API key
• [QUOTA_ERROR] - quota or rate limit exceeded
• [TIMEOUT_ERROR] - request timed out
• [API_ERROR] - other Gemini/API failures

License

MIT