Gemini Web MCP

An MCP server that brings Gemini-powered web tools to your AI coding assistant—web search, content extraction, deep research, and image generation.

✨ Features

| Tool | Description | |------|-------------| | search_web | Web search with AI-synthesized summaries and citations | | read_url_content | Extract and convert web content (HTML, PDF, JSON, Markdown, Plain Text, CSV, XML/RSS) to clean markdown | | view_content_chunk | Navigate large documents chunk by chunk | | start_deep_research | Initiate multi-step background research with Gemini's Deep Research Agent | | check_deep_research | Check status, uptime, error details, and retrieve synthesized research report | | create_image | Generate or edit images using natural language |

One-Click Install

| IDE | Install | |-----|---------| | Cursor | | | VS Code | | | VS Code Insiders | |

Note: After clicking, replace your-api-key with your Gemini API key. VS Code requires version 1.101+.

🚀 Installation

Using npx (Recommended)

Requires Node.js 22+ (Node.js 22 LTS or newer).

npx gemini-web-mcp

{
  "servers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "gemini-web-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "gemini-web-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "gemini-web-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json (macOS/Linux) or %USERPROFILE%\.codeium\windsurf\mcp_config.json (Windows):

{
  "mcpServers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "gemini-web-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "gemini-web-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "gemini-web-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

1. Open the Agent side panel → click ... → MCP Store
2. Click Add Custom Server
3. Add this configuration:

{
  "gemini-web": {
    "command": "npx",
    "args": ["-y", "gemini-web-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-api-key"
    }
  }
}

Using npm (Global Install)

npm install -g gemini-web-mcp

Then use gemini-web-mcp as the command instead of npx -y gemini-web-mcp in your MCP configs.

⚙️ Configuration

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | GEMINI_API_KEY | ✓ | — | Your Gemini API key (also supports GOOGLE_API_KEY fallback) | | GEMINI_WEBSEARCH_MODEL | | gemini-3.7-flash | Model for web search | | GEMINI_DEEP_RESEARCH_AGENT | | deep-research-preview-04-2026 | Deep Research agent name (deep-research-preview-04-2026 for standard speed, deep-research-max-preview-04-2026 for maximum thoroughness) | | GEMINI_IMAGE_MODEL | | gemini-3.1-flash-image | Image generation model | | LOG_LEVEL | | info | Logging level (debug, info, warn, error) |

🛠️ Tools Reference

search_web

Performs a web search and returns an AI-synthesized summary with citations.

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|---------|-------------| | query | string | ✓ | — | Search query | | domain | string | | — | Optional domain to recommend the search prioritize | | model | string | | Configured default | Override default search model |

read_url_content

Fetches a URL and converts its content to clean markdown. Supports HTML, PDF, JSON, Markdown, Plain Text, CSV, and XML/RSS. Returns chunk summaries for navigation.

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | url | string | ✓ | URL to fetch |

view_content_chunk

Retrieves a specific chunk from a previously fetched document.

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | document_id | string | ✓ | The URL used in read_url_content | | position | number | ✓ | Chunk position to view |

start_deep_research

Initiates a deep, multi-step web research job in the background using Google's Deep Research Agent. Returns a job_id, which you can use to check the status of completion using check_deep_research(job_id=...).

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|---------|-------------| | prompt | string | ✓ | — | Your comprehensive research question or topic |

Returns: { "job_id": "...", "status": "in_progress" }

check_deep_research

Checks the status of a Deep Research job using its job_id and returns the complete synthesized report once finished.

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|---------|-------------| | job_id | string | ✓ | — | The research tracking ID from start_deep_research | | include_citations | boolean | | true | Include resolved source URLs in the report |

Returns:

• In Progress: { "job_id": "...", "status": "in_progress", "uptime": "2m 15s" }
• Completed: { "job_id": "...", "status": "completed", "report_text": "..." }
• Failed: { "job_id": "...", "status": "failed", "error": "Error 403 - ..." }

create_image

Generate images from text prompts or edit existing images.

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|---------|-------------| | prompt | string | ✓ | — | Text description or edit instructions | | images | string[] | | — | File paths for image editing (up to 7) | | aspect_ratio | string | | "1:1" | "1:1", "16:9", "9:16", "4:3", "3:4" | | model | string | | Configured default | Override default image generation model |

🧑‍💻 Development

git clone https://github.com/bharatvansh/gemini-web-mcp.git
cd gemini-web-mcp
npm install
npm run dev

| Script | Description | |--------|-------------| | npm run dev | Run with hot reload | | npm run build | Build for production | | npm run typecheck | Type check only | | npm start | Start production server |

📄 License

MIT