Skip to main content
Glama

gpal

Python 3.12+ License: MIT MCP

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 ctx.session_id

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 traceparent from MCP requests

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

consult_gemini

auto (default)

Lite explores, then Flash synthesizes

consult_gemini

flash

Fast, efficient mapping and searching

consult_gemini

pro

Deep reasoning, complex reviews

consult_gemini_oneshot

flash / pro

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:4317

Context Caching

Reduce costs for large projects by caching context on Google's servers:

  1. Upload large files using upload_file.

  2. Create a cache using create_context_cache with the returned URIs.

  3. Reference the cache name in consult_gemini calls via the cached_content parameter.

  4. View active caches via the gpal://caches resource.

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_store

  • When stores exist, Gemini searches them automatically during consult_gemini calls

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 = true

Paths 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-prompt

Composition order:

  1. Built-in gpal system instruction (unless include_default_prompt = false or --no-default-prompt)

  2. Files from system_prompts in config.toml

  3. Inline system_prompt from config.toml

  4. Files from --system-prompt CLI flags

Check what's active via the gpal://info resource β€” it shows which sources contributed and the total instruction length.

Installation

Prerequisites

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 gpal

Usage

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_gemini to 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_execution or shell), and iterates until green.

  • Review Agent: specialized system instruction for code review that outputs structured comments.

Available Tools

20 tools
cancel_batchA
Destructive

Cancel a running batch job. Already-completed requests are unaffected.

Args: name: Batch job name from create_batch.

Inputs: name (required). Returns: object

consult_geminiA
Read-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_oneshotA
Read-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_cacheA
Idempotent

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_batchA
DestructiveIdempotent

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_cacheB
DestructiveIdempotent

Delete a Gemini context cache.

Inputs: cache_name (required). Returns: result

delete_file_storeA
Destructive

Delete a FileSearch store and all its documents.

Inputs: name (required). Returns: result

gemini_code_execA
Read-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

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_batchA
Read-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_resultsA
Read-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_batchesA
Read-only

List recent batch jobs.

Args: limit: Maximum number of batches to return (default: 20, max: 100).

Inputs: limit. Returns: object

list_file_storesA
Read-only

List all FileSearch stores with document counts and sizes.

Inputs: no named parameters. Returns: result

list_modelsA
Read-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_fileC
Idempotent

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

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    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 Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers