my-pal-mcp-server/docs/user-guides/configuration.md

Configuration Guide

This guide covers all configuration options for the Gemini MCP Server.

Environment Variables

Required Configuration

Variable	Description	Example
GEMINI_API_KEY	Your Gemini API key from Google AI Studio (replace entire placeholder)	AIzaSyC_your_actual_key_here

Optional Configuration

Variable	Default	Description
REDIS_URL	redis://localhost:6379/0	Redis connection URL for conversation threading
WORKSPACE_ROOT	$HOME	Root directory mounted as /workspace in container
LOG_LEVEL	INFO	Logging verbosity: DEBUG, INFO, WARNING, ERROR
GEMINI_MODEL	gemini-2.5-pro-preview-06-05	Gemini model to use
MAX_CONTEXT_TOKENS	1000000	Maximum context window (1M tokens for Gemini Pro)

Claude Desktop Configuration

MCP Server Configuration

Add to your Claude Desktop config file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration Options

Option 1: Published Docker Image (Recommended)

Simplest setup using pre-built images from GitHub Container Registry:

{
  "mcpServers": {
    "gemini": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GEMINI_API_KEY",
        "ghcr.io/beehiveinnovations/zen-mcp-server:latest"
      ],
      "env": {
        "GEMINI_API_KEY": "AIzaSyC_your_actual_gemini_api_key_here"
      }
    }
  }
}

Available Image Tags:

• latest - Most recent stable release (recommended)
• v1.2.0, v1.1.0 - Specific version tags
• pr-{number} - Development builds from pull requests
• main-{commit-sha} - Development builds from main branch

Benefits:

• ✅ No local build required - instant setup
• ✅ Automatically updated with releases
• ✅ Smaller local footprint
• ✅ Version pinning for stability
• ✅ Cross-platform compatibility

Version Pinning Example:

{
  "mcpServers": {
    "gemini": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GEMINI_API_KEY",
        "ghcr.io/beehiveinnovations/zen-mcp-server:v1.2.0"
      ],
      "env": {
        "GEMINI_API_KEY": "AIzaSyC_your_actual_gemini_api_key_here"
      }
    }
  }
}

Option 2: Local Development Build

• Windows (WSL): /mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "gemini": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "zen-mcp-server",
        "python",
        "server.py"
      ]
    }
  }
}

Alternative: Claude Code CLI

# Add MCP server via CLI
claude mcp add gemini -s user -- docker exec -i zen-mcp-server python server.py

# List servers
claude mcp list

# Remove server
claude mcp remove gemini -s user

Docker Configuration

Environment File (.env)

# Required
GEMINI_API_KEY=your-gemini-api-key-here

# Optional - Docker Compose defaults
REDIS_URL=redis://redis:6379/0
WORKSPACE_ROOT=/Users/yourname
LOG_LEVEL=INFO

Docker Compose Overrides

Create docker-compose.override.yml for custom settings:

services:
  gemini-mcp:
    environment:
      - LOG_LEVEL=DEBUG
    volumes:
      - /custom/path:/workspace:ro

Logging Configuration

Log Levels

• DEBUG: Detailed operational messages, conversation threading, tool execution flow
• INFO: General operational messages (default)
• WARNING: Warnings and errors only
• ERROR: Errors only

Viewing Logs

# Real-time logs
docker compose logs -f gemini-mcp

# Specific service logs
docker compose logs redis
docker compose logs log-monitor

Security Configuration

API Key Security

1. Never commit API keys to version control
2. Use environment variables or .env files
3. Restrict key permissions in Google AI Studio
4. Rotate keys periodically

File Access Security

The container mounts your home directory as read-only. To restrict access:

# In docker-compose.override.yml
services:
  gemini-mcp:
    environment:
      - WORKSPACE_ROOT=/path/to/specific/project
    volumes:
      - /path/to/specific/project:/workspace:ro

Performance Configuration

Memory Limits

# In docker-compose.override.yml
services:
  gemini-mcp:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

Redis Configuration

Redis is pre-configured with optimal settings:

• 512MB memory limit
• LRU eviction policy
• Persistence enabled (saves every 60 seconds if data changed)

To customize Redis:

# In docker-compose.override.yml
services:
  redis:
    command: redis-server --maxmemory 1g --maxmemory-policy allkeys-lru

Troubleshooting Configuration

Common Issues

1. API Key Not Set

   # Check .env file
   cat .env | grep GEMINI_API_KEY
   

2. File Access Issues

   # Check mounted directory
   docker exec -it zen-mcp-server ls -la /workspace
   

3. Redis Connection Issues

   # Test Redis connectivity
   docker exec -it gemini-mcp-redis redis-cli ping
   

Debug Mode

Enable debug logging for troubleshooting:

# In .env file
LOG_LEVEL=DEBUG

# Restart services
docker compose restart

Advanced Configuration

Custom Model Configuration

To use a different Gemini model, override in .env:

GEMINI_MODEL=gemini-2.5-pro-latest

Network Configuration

For custom networking (advanced users):

# In docker-compose.override.yml
networks:
  custom_network:
    driver: bridge

services:
  gemini-mcp:
    networks:
      - custom_network
  redis:
    networks:
      - custom_network

---

See Also:

• Installation Guide
• Troubleshooting Guide