Gemini Agent MCP Server

An advanced Model Context Protocol (MCP) server that provides three purpose-built agent tools — web search, URL analysis, and code execution — via Gemini Flash models on Vertex AI.

Unlike a standard search tool, this server separates each capability into its own MCP tool, so your AI client (goose, Claude Desktop, etc.) can orchestrate real-time Google Search, deep URL analysis, and Python code execution across multiple requests to solve complex, multi-step research and data tasks.

Features

• Search Grounding: Uses Google Search to find up-to-the-minute information.

• URL Context: Automatically fetches and parses the content of specific web pages for deep analysis.

• Code Execution: Writes and executes Python code on-the-fly to perform calculations, data manipulation, or logical reasoning.

• Thinking Mode: Uses Gemini's internal reasoning to plan and refine its approach before answering — a 512-token thinking budget by default, overridable with GEMINI_THINKING_LEVEL or GEMINI_THINKING_BUDGET.

Related MCP server: Gemini Research MCP Server

Prerequisites

1. Google Cloud Project: You must have a Google Cloud project with the Vertex AI API enabled.

2. Authentication: You must have gcloud CLI installed and authenticated:

   gcloud auth application-default login

3. Permissions: Your account needs the Vertex AI User role on the project.

Configuration

The server requires the following environment variables:

Note: GOOGLE_CLOUD_PROJECT can also be used instead of GCP_PROJECT_ID, and GOOGLE_CLOUD_LOCATION instead of GCP_LOCATION.

Installation & Usage

1. Build the project

npm install
npm run build

2. Integration with Goose

Add the following to your ~/.config/goose/profiles.yaml (or manage via the Goose UI):

  gemini-agent:
    cmd: node
    args:
      - /path/to/gemini-agent-mcp/build/index.js
    envs:
      GCP_PROJECT_ID: "your-project-id"
      GCP_LOCATION: "global"

3. Integration with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-agent": {
      "command": "node",
      "args": ["/path/to/gemini-agent-mcp/build/index.js"],
      "env": {
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_LOCATION": "global",
        "PATH": "/usr/local/bin:/usr/bin:/bin" 
      }
    }
  }
}

Tools

The server exposes three purpose-built tools. Because the underlying model rejects requests that combine multiple tools ("Multiple tools are supported only when they are all search tools"), each tool makes a single-tool Gemini call; orchestration across capabilities happens at the client level.

gemini_web_search

Search the web using Google Search grounding and get an AI-synthesized answer with up-to-the-minute information.

• Arguments: query (string, required)

• Use for: current events, recent releases, news, or any question where search results would improve the answer.

gemini_url_context

Fetches and deeply analyzes the content of specific web page URLs.

• Arguments: urls (array of URLs, required), instruction (string, optional — what to learn from the page(s))

• Use for: when you have a concrete URL and want to extract, summarize, or answer questions about its content.

gemini_code_execution

Writes and executes Python code in a Gemini sandbox to solve computational problems.

• Arguments: task (string, required — described in plain language)

• Use for: math, data analysis, statistics, data transformation, simulations, or logical reasoning.

ask_gemini_agent (legacy)

The original all-in-one tool, kept for backward compatibility with existing client configurations. Because the configured model cannot combine tools in one request, it now performs a single search-grounded call — prefer the three purpose-built tools above.

Limitations

• Model: Defaults to gemini-3.8-flash (current Gemini Flash model on Vertex AI, global location). Override with GEMINI_MODEL to any model available for your project and GCP_LOCATION. Note: Developer-API aliases such as gemini-flash-latest do not exist as Vertex AI publisher models and fail with 404 — see the model documentation.

• One Tool Per Request: The model supports search, URL context, and code execution individually, but the API rejects combining them in a single request; the server automatically falls back to a single tool (search first) if the combined request is rejected.

• Python-only Code Execution: The code execution environment is restricted to standard Python libraries provided by the Gemini sandbox.

• Stdio Transport: This server currently only supports standard I/O communication.

Testing

npm run test:integration runs an end-to-end smoke test over stdio: it launches the built server with GEMINI_MODEL unset (exercising the built-in default model), verifies all four tools are registered, and issues one live search-grounded request. It requires Google Application Default Credentials ("gcloud auth application-default login") and network access.

npm run build
npm run test:integration

License

MIT