feat: add setup scripts and improve dependency installation

- Add setup.sh for macOS/Linux with dependency installation
- Add setup.bat for Windows with dependency installation
- Update README with clearer setup instructions in Quickstart
- Add troubleshooting for "ModuleNotFoundError: No module named 'mcp'"
- Provide manual installation steps as fallback

This helps users avoid the common "ModuleNotFoundError" by ensuring
dependencies are properly installed before first use.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -35,21 +35,35 @@ All tools accept both individual files and entire directories. The server:
 ### 1. Get a Gemini API Key
 Visit [Google AI Studio](https://makersuite.google.com/app/apikey) and generate an API key. For best results with Gemini 2.5 Pro, use a paid API key as the free tier has limited access to the latest models.
 
-### 2. Clone the Repository
+### 2. Clone and Set Up the Repository
-Clone this repository to a location on your computer:
+Clone this repository to a location on your computer and install dependencies:
 
 ```bash
 # Example: Clone to your home directory
 cd ~
 git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
+cd gemini-mcp-server
 
-# The server is now at: ~/gemini-mcp-server
+# Run the setup script to install dependencies
+# macOS/Linux:
+./setup.sh
+
+# Windows:
+setup.bat
 ```
 
 **Note the full path** - you'll need it in the next step:
 - **macOS/Linux**: `/Users/YOUR_USERNAME/gemini-mcp-server`
 - **Windows**: `C:\Users\YOUR_USERNAME\gemini-mcp-server`
 
+**Important**: The setup script will:
+- Create a Python virtual environment
+- Install all required dependencies (mcp, google-genai, etc.)
+- Verify your Python installation
+- Provide next steps for configuration
+
+If you encounter any issues during setup, see the [Troubleshooting](#troubleshooting) section.
+
 ### 3. Configure Claude Desktop
 Add the server to your `claude_desktop_config.json`:
 
@@ -876,6 +890,26 @@ This error occurs when Claude Desktop (running on Windows) can't properly execut
 
 ### Common Issues
 
+**"ModuleNotFoundError: No module named 'mcp'"**
+- This means Python dependencies aren't installed
+- **Solution**: Run the setup script:
+  - macOS/Linux: `./setup.sh` 
+  - Windows: `setup.bat`
+- If you still see this error, manually activate the virtual environment and install:
+  ```bash
+  # macOS/Linux:
+  source venv/bin/activate
+  pip install -r requirements.txt
+  
+  # Windows:
+  venv\Scripts\activate.bat
+  pip install -r requirements.txt
+  ```
+
+**"Virtual environment not found" warning**
+- This is just a warning that can be ignored if dependencies are installed system-wide
+- To fix: Run the setup script to create the virtual environment
+
 **"GEMINI_API_KEY environment variable is required"**
 - Ensure you've added your API key to the Claude Desktop configuration
 - The key should be in the `env` section of your MCP server config

setup.bat

@@ -0,0 +1,66 @@
+@echo off
+REM Gemini MCP Server Setup Script for Windows
+REM This script helps users set up the virtual environment and install dependencies
+
+echo Gemini MCP Server Setup
+echo =======================
+
+REM Get the directory where this script is located
+set SCRIPT_DIR=%~dp0
+cd /d "%SCRIPT_DIR%"
+
+REM Check if Python is installed
+python --version >nul 2>&1
+if errorlevel 1 (
+    echo Error: Python is not installed or not in PATH.
+    echo Please install Python 3.10 or higher from https://python.org
+    echo Make sure to check "Add Python to PATH" during installation.
+    exit /b 1
+)
+
+REM Display Python version
+echo Found Python:
+python --version
+
+REM Check if venv exists
+if exist "venv\" (
+    echo Virtual environment already exists
+) else (
+    echo Creating virtual environment...
+    python -m venv venv
+    if errorlevel 1 (
+        echo Error: Failed to create virtual environment
+        exit /b 1
+    )
+    echo Virtual environment created
+)
+
+REM Activate virtual environment
+echo Activating virtual environment...
+call venv\Scripts\activate.bat
+
+REM Upgrade pip
+echo Upgrading pip...
+python -m pip install --upgrade pip
+
+REM Install requirements
+echo Installing dependencies...
+pip install -r requirements.txt
+
+if errorlevel 1 (
+    echo.
+    echo Error: Failed to install dependencies
+    echo Please check the error messages above and try again.
+    exit /b 1
+) else (
+    echo.
+    echo Setup completed successfully!
+    echo.
+    echo Next steps:
+    echo 1. Get your Gemini API key from: https://makersuite.google.com/app/apikey
+    echo 2. Configure Claude Desktop with your API key (see README.md)
+    echo 3. Restart Claude Desktop
+    echo.
+    echo Note: The virtual environment has been activated for this session.
+    echo The run_gemini.bat script will automatically activate it when needed.
+)

setup.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+# Gemini MCP Server Setup Script
+# This script helps users set up the virtual environment and install dependencies
+
+echo "🚀 Gemini MCP Server Setup"
+echo "========================="
+
+# Get the directory where this script is located
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$SCRIPT_DIR"
+
+# Check if Python is installed
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Error: Python 3 is not installed."
+    echo "Please install Python 3.10 or higher from https://python.org"
+    exit 1
+fi
+
+# Display Python version
+PYTHON_VERSION=$(python3 --version)
+echo "✓ Found $PYTHON_VERSION"
+
+# Check if venv exists
+if [ -d "venv" ]; then
+    echo "✓ Virtual environment already exists"
+else
+    echo "📦 Creating virtual environment..."
+    python3 -m venv venv
+    if [ $? -eq 0 ]; then
+        echo "✓ Virtual environment created"
+    else
+        echo "❌ Error: Failed to create virtual environment"
+        exit 1
+    fi
+fi
+
+# Activate virtual environment
+echo "🔧 Activating virtual environment..."
+source venv/bin/activate
+
+# Upgrade pip
+echo "📦 Upgrading pip..."
+pip install --upgrade pip
+
+# Install requirements
+echo "📦 Installing dependencies..."
+pip install -r requirements.txt
+
+if [ $? -eq 0 ]; then
+    echo ""
+    echo "✅ Setup completed successfully!"
+    echo ""
+    echo "Next steps:"
+    echo "1. Get your Gemini API key from: https://makersuite.google.com/app/apikey"
+    echo "2. Configure Claude Desktop with your API key (see README.md)"
+    echo "3. Restart Claude Desktop"
+    echo ""
+    echo "Note: The virtual environment has been activated for this session."
+    echo "The run_gemini.sh script will automatically activate it when needed."
+else
+    echo "❌ Error: Failed to install dependencies"
+    echo "Please check the error messages above and try again."
+    exit 1
+fi