gpal
Provides access to Google Gemini models for autonomous codebase exploration and analysis, supporting stateful sessions, multimodal inputs, context caching, and semantic search.
Integrates native OpenTelemetry support for monitoring and distributed tracing, with automatic traceparent header propagation from MCP requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gpal Explain authentication flow in this project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gpal
An MCP server that gives your IDE or agent access to Google Gemini with autonomous codebase exploration. Your pal Gemini.
Why gpal?
When you ask gpal a question, Gemini doesn't just guess β it explores your codebase itself. It lists directories, reads files, and searches for patterns before answering. This makes it ideal for:
π Deep code analysis β "Find all error handling patterns in this codebase"
ποΈ Architectural reviews β "How is authentication implemented?"
π Bug hunting β "Why might this function return null?"
π Codebase onboarding β "Explain how the request pipeline works"
πΌοΈ Visual review β Analyze screenshots, diagrams, video via
media_pathsπ Structured extraction β "List all API endpoints as JSON"
Related MCP server: Gemini Bridge
Features
Feature | Description |
Stateful sessions | Maintains conversation history via |
Autonomous exploration | Gemini has tools to list, read, and search files |
FileSearch | Semantic code search via Google's native FileSearch API |
Gemini 3 Series | Supports Flash and Pro with unified auto mode |
Context Caching | Store large code contexts to reduce costs and latency |
Observability | Native OpenTelemetry support (OTLP gRPC) |
Distributed Tracing | Propagates |
Multimodal | Analyze images, audio, video, PDFs |
Batch Processing | Async discounted (~50%) Gemini batch API |
Limits: 10MB file reads, 20MB inline media, 20 search matches max.
Model Tiers
Tool | Model | Use Case |
|
| Lite explores, then Flash synthesizes |
|
| Fast, efficient mapping and searching |
|
| Deep reasoning, complex reviews |
|
| Stateless single-shot queries, no session history |
Auto mode: Lite autonomously explores the codebase (cheap, thorough), then Flash synthesizes over what Lite found. Use model="pro" for deep reasoning (Lite explores, then Pro with thinking HIGH).
Observability & Tracing
gpal supports native OpenTelemetry for monitoring and distributed tracing. It automatically propagates traceparent headers from incoming MCP requests.
# Configure via standard environment variables
export OTEL_SERVICE_NAME="gpal-server"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
# Or via CLI argument
uv run gpal --otel-endpoint localhost:4317Context Caching
Reduce costs for large projects by caching context on Google's servers:
Upload large files using
upload_file.Create a cache using
create_context_cachewith the returned URIs.Reference the cache name in
consult_geminicalls via thecached_contentparameter.View active caches via the
gpal://cachesresource.
FileSearch
Semantic code search using Google's native FileSearch API β no local embeddings or databases:
# Create a store and upload files
create_file_store("my-project")
upload_to_file_store("stores/...", "src/server.py")
# Gemini searches stores automatically during generation
consult_gemini("find authentication logic", model="auto")Google handles chunking, embedding, and retrieval
Stores managed via
create_file_store,upload_to_file_store,list_file_stores,delete_file_storeWhen stores exist, Gemini searches them automatically during
consult_geminicalls
Custom System Prompts
Customize what Gemini "knows" about you, your project, or your workflow by composing system prompts from multiple sources.
Config file (~/.config/gpal/config.toml):
# Files loaded in order and concatenated
system_prompts = [
"~/.config/gpal/GEMINI.md",
"~/CLAUDE.md",
]
# Inline text appended after files
system_prompt = "εΈΈγ«ζ₯ζ¬θͺγ§εηγγ¦γγ γγ (Always respond in Japanese)"
# Set to false to fully replace the built-in prompt with your own
include_default_prompt = truePaths support ~ and $ENV_VAR expansion, so you can use $WORKSPACE/CLAUDE.md etc.
CLI flags (repeatable, concatenated in order):
# Append additional prompt files
uv run gpal --system-prompt /path/to/project-context.md
# Multiple files
uv run gpal --system-prompt ~/GEMINI.md --system-prompt ./CLAUDE.md
# Replace the built-in prompt entirely
uv run gpal --system-prompt ~/my-prompt.md --no-default-promptComposition order:
Built-in gpal system instruction (unless
include_default_prompt = falseor--no-default-prompt)Files from
system_promptsin config.tomlInline
system_promptfrom config.tomlFiles from
--system-promptCLI flags
Check what's active via the gpal://info resource β it shows which sources contributed and the total instruction length.
Installation
Prerequisites
Python 3.12+
uv (recommended)
Quick Start
git clone https://github.com/tobert/gpal.git
cd gpal
export GEMINI_API_KEY="your_key_here" # or GOOGLE_API_KEY
uv run gpalUsage
Claude Desktop / Cursor / VS Code
Add to your MCP config (e.g., claude_desktop_config.json):
{
"mcpServers": {
"gpal": {
"command": "uv",
"args": ["--directory", "/path/to/gpal", "run", "gpal"],
"env": {
"GEMINI_API_KEY": "your_key_here"
}
}
}
}Then ask your AI assistant:
"Ask Gemini to analyze the authentication flow in this codebase"
"Use
consult_geminito find where errors are handled"
Development
uv run pytest # Run tests
uv run pytest -v # Verbose outputβ οΈ Note: Integration tests (test_connectivity.py, test_agentic.py, test_switching.py) make live API calls and will incur Gemini API costs.
See Also
cpal β The inverse: an MCP server that lets Gemini (or any MCP client) consult Claude. Your pal Claude.
License
MIT β see LICENSE
Roadmap / TODO
Refactoring Agent: A loop that edits files, runs tests (via
code_executionor shell), and iterates until green.Review Agent: specialized system instruction for code review that outputs structured comments.
Available Tools
20 toolscancel_batchADestructive
Cancel a running batch job. Already-completed requests are unaffected.
Args: name: Batch job name from create_batch.
Inputs: name (required). Returns: object
consult_geminiARead-only
Consult Gemini for codebase analysis.
Gemini autonomously explores our project β reading files, listing directories, and searching code β so we don't need to pre-read files. Just describe what we need. Use file_paths only when specific files must be included.
Pipeline: For auto, flash, and pro, Lite explores quickly first, then our selected model synthesizes. "lite" and explicit model IDs skip the exploration phase and query directly. Gemini's tools: list_directory, read_file, search_project, git, gemini_search; FileSearch stores are searched automatically when present.
Inputs: query (required), model, file_paths, media_paths, +5 more.
consult_gemini_oneshotARead-only
Stateless single-shot Gemini query with no session history.
Use for independent questions, one-off lookups, or batch-style queries where conversation context would be noise. Still has tool access (list_directory, read_file, etc.) and retry logic.
Inputs: query (required), model, file_paths, media_paths, +5 more.
create_batchA
Submit a batch of queries for async processing (~50% cost discount).
Batches run asynchronously (up to 24h). No tool use β inline all relevant context in each prompt. Use get_batch/list_batches to check status and get_batch_results when the job completes.
The system prompt follows the same configuration as consult_gemini (config.toml, --system-prompt CLI flags).
Args: queries: List of {custom_id: str, prompt: str} dicts. model: Model alias or ID (default: "flash"). "pro" enables deep thinking. temperature: Sampling temperature (default: 0.2).
Inputs: queries (required), model, temperature. Returns: object
create_context_cacheAIdempotent
Create a Gemini context cache for a set of files.
Caching is useful for large files (>32k tokens) used across multiple turns. Model must be an explicit version (e.g., gemini-1.5-flash-001) or a supported alias.
Inputs: file_uris (required), model, display_name, ttl_seconds. Returns: result
create_file_storeA
Create a new FileSearch store for semantic code search.
Upload files to the store with upload_to_file_store. Once populated, Gemini will automatically search the store during consult_gemini calls.
Inputs: display_name (required). Returns: result
delete_batchADestructiveIdempotent
Delete a batch job. Only works on ended (succeeded/failed/cancelled) jobs.
Args: name: Batch job name from create_batch.
Inputs: name (required). Returns: object
delete_context_cacheBDestructiveIdempotent
Delete a Gemini context cache.
Inputs: cache_name (required). Returns: result
delete_file_storeADestructive
Delete a FileSearch store and all its documents.
Inputs: name (required). Returns: result
gemini_code_execARead-only
Execute Python code using Gemini's built-in code execution sandbox.
Returns stdout, stderr, and any execution results. Stateless utility.
Inputs: code (required), model. Returns: result
gemini_searchARead-only
Search the web using Gemini's built-in Google Search.
Returns formatted search results (titles, URLs, snippets). Stateless utility.
Inputs: query (required), num_results, model. Returns: result
generate_imageA
Generates an image using Imagen or Nano Banana (Gemini image) models.
Args: prompt: Text description of the image to generate. output_path: File path to save the generated image. model: Model alias or ID. "imagen" (default, ultra), "imagen-fast", "nano-pro", or "nano-flash". aspect_ratio: Aspect ratio (e.g. "1:1", "16:9", "9:16", "4:3", "3:4"). image_size: Output size for Nano Banana only (e.g. "1024x1024"). Not supported by Imagen.
Inputs: prompt (required), output_path (required), model, aspect_ratio, +1 more. Returns: result
generate_speechB
Synthesizes speech from text.
Inputs: text (required), output_path (required), voice_name, model. Returns: result
get_batchARead-only
Get the status of a batch job.
Args: name: Batch job name (e.g. "batches/abc") from create_batch.
Inputs: name (required). Returns: object
get_batch_resultsARead-only
Get results from a completed batch job.
Only available when state is JOB_STATE_SUCCEEDED or JOB_STATE_PARTIALLY_SUCCEEDED. Results include text extracted from each response, keyed by custom_id.
Args: name: Batch job name from create_batch.
Inputs: name (required). Returns: object
list_batchesARead-only
List recent batch jobs.
Args: limit: Maximum number of batches to return (default: 20, max: 100).
Inputs: limit. Returns: object
list_file_storesARead-only
List all FileSearch stores with document counts and sizes.
Inputs: no named parameters. Returns: result
list_modelsARead-onlyIdempotent
List available Gemini models grouped by capability.
Queries the Gemini API for all accessible models and groups them by supported actions (generateContent, generateImages, embedContent, etc.).
Inputs: no named parameters. Returns: result
upload_fileCIdempotent
Upload a large file to Gemini's File API.
Inputs: file_path (required), display_name. Returns: result
upload_to_file_storeA
Upload a file to a FileSearch store for semantic search.
Supported: text, code, PDF, and other document formats. Files are chunked and embedded by Google for retrieval.
Inputs: store_name (required), file_path (required), display_name. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 20 tools
Most tools have clearly distinct purposes, but consult_gemini and consult_gemini_oneshot overlap significantly (both query Gemini, differing only in statefulness). The descriptions help differentiate them, but the similarity could cause misselection.
Naming is mostly snake_case and verb-driven (e.g., create_batch, delete_file_store), but some tools start with nouns (gemini_code_exec, gemini_search) and there's no consistent pattern like verb_noun. This inconsistency may confuse agents.
20 tools is on the higher side but still reasonable for wrapping Gemini's extensive API. Each tool covers a distinct feature (batch, file stores, caching, search, generation), so the count feels appropriate.
The tool set covers major Gemini capabilities: batch processing, file management, caching, code execution, web search, image/speech generation, and model listing. Minor gaps exist (e.g., no tool to list uploaded files or update cache settings), but core workflows are solid.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseBqualityDmaintenanceA lightweight MCP server that enables AI agents to perform deep codebase analysis by leveraging Gemini's massive context window for cross-file analysis and intelligent file selection.428MIT
- AlicenseAqualityFmaintenanceA lightweight MCP server that enables AI coding assistants to interact with Google's Gemini AI through the official CLI.3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that integrates Google Gemini CLI with Claude Code for AI-powered development assistance, enabling code review, bug analysis, feature planning, and code explanation without requiring an API key.8MIT
- AlicenseAqualityDmaintenanceGemini-powered MCP server for automated code review, analysis, and documentation.13MIT