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_LEVELorGEMINI_THINKING_BUDGET.
Prerequisites
- Google Cloud Project: You must have a Google Cloud project with the Vertex AI API enabled.
- Authentication: You must have gcloud CLI installed and authenticated:
bash gcloud auth application-default login - Permissions: Your account needs the
Vertex AI Userrole on the project.
Configuration
The server requires the following environment variables:
| Variable | Description | Default |
|---|---|---|
GCP_PROJECT_ID |
Your Google Cloud Project ID (Required) | - |
GCP_LOCATION |
Vertex AI location | global |
GEMINI_MODEL |
Gemini model ID to call; must be available for the project and location on Vertex AI | gemini-3.8-flash |
GEMINI_THINKING_LEVEL |
Overrides thinking depth (low, medium, high, or minimal); takes precedence over the budget. Note: support varies by model — gemini-3.8-flash rejects minimal |
unset |
GEMINI_THINKING_BUDGET |
Thinking budget in tokens | 512 |
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```bash
npm install
npm run build
### 2. Integration with Goose
Add the following to your `~/.config/goose/profiles.yaml` (or manage via the Goose UI):```yaml
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:```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.```bash
npm run build
npm run test:integration
License
MIT
