up
This commit is contained in:
Patryk Ciechanski
233
docs/user-guides/configuration.md
Normal file
233
docs/user-guides/configuration.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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 | `AIzaSyC...` |
|
||||
|
||||
### 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`
|
||||
- **Windows (WSL)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json`
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"exec",
|
||||
"-i",
|
||||
"gemini-mcp-server",
|
||||
"python",
|
||||
"server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Alternative: Claude Code CLI
|
||||
|
||||
```bash
|
||||
# Add MCP server via CLI
|
||||
claude mcp add gemini -s user -- docker exec -i gemini-mcp-server python server.py
|
||||
|
||||
# List servers
|
||||
claude mcp list
|
||||
|
||||
# Remove server
|
||||
claude mcp remove gemini -s user
|
||||
```
|
||||
|
||||
## Docker Configuration
|
||||
|
||||
### Environment File (.env)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# 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**
|
||||
```bash
|
||||
# Check .env file
|
||||
cat .env | grep GEMINI_API_KEY
|
||||
```
|
||||
|
||||
2. **File Access Issues**
|
||||
```bash
|
||||
# Check mounted directory
|
||||
docker exec -it gemini-mcp-server ls -la /workspace
|
||||
```
|
||||
|
||||
3. **Redis Connection Issues**
|
||||
```bash
|
||||
# Test Redis connectivity
|
||||
docker exec -it gemini-mcp-redis redis-cli ping
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```bash
|
||||
GEMINI_MODEL=gemini-2.5-pro-latest
|
||||
```
|
||||
|
||||
### Network Configuration
|
||||
|
||||
For custom networking (advanced users):
|
||||
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
networks:
|
||||
custom_network:
|
||||
driver: bridge
|
||||
|
||||
services:
|
||||
gemini-mcp:
|
||||
networks:
|
||||
- custom_network
|
||||
redis:
|
||||
networks:
|
||||
- custom_network
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- [Installation Guide](installation.md)
|
||||
- [Troubleshooting Guide](troubleshooting.md)
|
||||
321
docs/user-guides/installation.md
Normal file
321
docs/user-guides/installation.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 🐳 Docker User Guide: Using Gemini MCP Server
|
||||
|
||||
This guide shows you how to use the Gemini MCP Server with Claude Desktop using the automated Docker setup. **Everything is handled automatically** - no manual Redis setup required!
|
||||
|
||||
## 🎯 What You'll Get
|
||||
|
||||
After following this guide, you'll have:
|
||||
- ✅ Gemini MCP Server running with Claude Desktop
|
||||
- ✅ Redis automatically configured for conversation threading
|
||||
- ✅ Access to all Gemini tools: `chat`, `thinkdeep`, `codereview`, `debug`, `analyze`, `precommit`
|
||||
- ✅ Persistent data storage that survives container restarts
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
### Required
|
||||
1. **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop/)
|
||||
2. **Claude Desktop** - [Download here](https://claude.ai/download)
|
||||
3. **Gemini API Key** - [Get one here](https://makersuite.google.com/app/apikey)
|
||||
4. **Git** - For cloning the repository
|
||||
|
||||
### Platform Support
|
||||
- ✅ **macOS** (Intel and Apple Silicon)
|
||||
- ✅ **Linux**
|
||||
- ✅ **Windows** (requires WSL2 for Claude Desktop)
|
||||
|
||||
## 🚀 Setup Option 1: Clone & Run (Recommended)
|
||||
|
||||
### Step 1: Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
|
||||
cd gemini-mcp-server
|
||||
```
|
||||
|
||||
### Step 2: One-Command Setup
|
||||
|
||||
```bash
|
||||
# Automated setup - builds images and starts all services
|
||||
./setup-docker.sh
|
||||
```
|
||||
|
||||
**What this script does automatically:**
|
||||
- ✅ Creates `.env` file with your API key (if `GEMINI_API_KEY` environment variable is set)
|
||||
- ✅ Builds the Gemini MCP Server Docker image
|
||||
- ✅ Starts Redis container for conversation threading
|
||||
- ✅ Starts MCP server container
|
||||
- ✅ Configures networking between containers
|
||||
- ✅ Shows you the exact Claude Desktop configuration
|
||||
|
||||
### Step 3: Add Your API Key (if needed)
|
||||
|
||||
If you see a message about updating your API key:
|
||||
|
||||
```bash
|
||||
# Edit .env file and replace placeholder with your actual key
|
||||
nano .env
|
||||
# Change: GEMINI_API_KEY=your-gemini-api-key-here
|
||||
# To: GEMINI_API_KEY=your_actual_api_key
|
||||
|
||||
# Restart services to apply changes
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
### Step 4: Configure Claude Desktop
|
||||
|
||||
The setup script shows you the exact configuration. Add this to your Claude Desktop config:
|
||||
|
||||
**Find your config file:**
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows (WSL)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json`
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"exec",
|
||||
"-i",
|
||||
"gemini-mcp-server",
|
||||
"python",
|
||||
"server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Restart Claude Desktop & Test
|
||||
|
||||
1. Completely quit and restart Claude Desktop
|
||||
2. Test with: `"Use gemini to chat about Python best practices"`
|
||||
|
||||
## 🚀 Setup Option 2: Published Docker Image (Advanced)
|
||||
|
||||
If you prefer to use the published image without cloning:
|
||||
|
||||
```bash
|
||||
# Create a directory for your work
|
||||
mkdir gemini-mcp-project && cd gemini-mcp-project
|
||||
|
||||
# Create minimal docker-compose.yml
|
||||
cat > docker-compose.yml << 'EOF'
|
||||
services:
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: gemini-mcp-redis
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "6379:6379"
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
|
||||
gemini-mcp:
|
||||
image: ghcr.io/beehiveinnovations/gemini-mcp-server:latest
|
||||
container_name: gemini-mcp-server
|
||||
restart: unless-stopped
|
||||
depends_on:
|
||||
- redis
|
||||
environment:
|
||||
- GEMINI_API_KEY=${GEMINI_API_KEY}
|
||||
- REDIS_URL=redis://redis:6379/0
|
||||
- WORKSPACE_ROOT=${HOME}
|
||||
volumes:
|
||||
- ${HOME}:/workspace:ro
|
||||
stdin_open: true
|
||||
tty: true
|
||||
|
||||
volumes:
|
||||
redis_data:
|
||||
EOF
|
||||
|
||||
# Create .env file
|
||||
echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env
|
||||
|
||||
# Start services
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## 🛠️ Available Tools
|
||||
|
||||
Once set up, you can use any of these tools naturally in Claude:
|
||||
|
||||
| Tool | Example Usage |
|
||||
|------|---------------|
|
||||
| **`chat`** | "Use gemini to brainstorm API design ideas" |
|
||||
| **`thinkdeep`** | "Use gemini to think deeper about this architecture" |
|
||||
| **`codereview`** | "Use gemini to review my Python code for security issues" |
|
||||
| **`debug`** | "Use gemini to debug this error: [paste stack trace]" |
|
||||
| **`analyze`** | "Use gemini to analyze my project structure" |
|
||||
| **`precommit`** | "Use gemini to validate my git changes before commit" |
|
||||
|
||||
## 📁 File Access
|
||||
|
||||
The Docker setup automatically mounts your home directory as `/workspace`. This means:
|
||||
|
||||
- ✅ Gemini can read files anywhere in your home directory
|
||||
- ✅ You can analyze entire projects: "Use gemini to analyze my ~/Projects/myapp/src/ directory"
|
||||
- ✅ Works with absolute paths: "Use gemini to review /Users/yourname/project/main.py"
|
||||
|
||||
## 🔧 Management Commands
|
||||
|
||||
### Check Status
|
||||
```bash
|
||||
# See if containers are running
|
||||
docker compose ps
|
||||
|
||||
# Should show both 'gemini-mcp-redis' and 'gemini-mcp-server' as 'Up'
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Check MCP server logs
|
||||
docker compose logs gemini-mcp -f
|
||||
|
||||
# Check Redis logs
|
||||
docker compose logs redis -f
|
||||
|
||||
# View all logs
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### Update to Latest Version
|
||||
```bash
|
||||
# For cloned repository setup
|
||||
git pull origin main
|
||||
./setup-docker.sh
|
||||
|
||||
# For published image setup
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Stop/Start Services
|
||||
```bash
|
||||
# Stop containers (keeps data)
|
||||
docker compose stop
|
||||
|
||||
# Start containers again
|
||||
docker compose start
|
||||
|
||||
# Restart all services
|
||||
docker compose restart
|
||||
|
||||
# Stop and remove everything
|
||||
docker compose down
|
||||
|
||||
# Stop and remove everything including volumes (⚠️ deletes Redis data)
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## 🔒 Security Notes
|
||||
|
||||
1. **API Key**: Your Gemini API key is stored in the container environment. The `.env` file is gitignored for security.
|
||||
|
||||
2. **File Access**: The container can read files in your home directory (mounted as read-only). This is necessary for file analysis.
|
||||
|
||||
3. **Network**: Redis runs on localhost:6379 but is only accessible to the MCP server container by default.
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### "Connection failed" in Claude Desktop
|
||||
```bash
|
||||
# Check if containers are running
|
||||
docker compose ps
|
||||
|
||||
# Should show both containers as 'Up'
|
||||
# If not, check logs:
|
||||
docker compose logs gemini-mcp
|
||||
```
|
||||
|
||||
### "GEMINI_API_KEY environment variable is required"
|
||||
```bash
|
||||
# Edit your .env file
|
||||
nano .env
|
||||
# Update: GEMINI_API_KEY=your_actual_api_key
|
||||
|
||||
# Restart services
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
### Containers won't start
|
||||
```bash
|
||||
# Check logs for specific errors
|
||||
docker compose logs
|
||||
|
||||
# Rebuild and restart
|
||||
docker compose down
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
### Tools not responding
|
||||
```bash
|
||||
# Check container resources
|
||||
docker stats
|
||||
|
||||
# Restart everything
|
||||
docker compose restart
|
||||
|
||||
# If still having issues, check Claude Desktop config
|
||||
```
|
||||
|
||||
### Permission issues (Linux)
|
||||
```bash
|
||||
# Ensure proper ownership
|
||||
sudo chown -R $USER:$USER .
|
||||
|
||||
# Make setup script executable
|
||||
chmod +x setup-docker.sh
|
||||
```
|
||||
|
||||
## 💡 How It Works (Technical Details)
|
||||
|
||||
The setup uses Docker Compose to orchestrate two services:
|
||||
|
||||
1. **Redis Container** (`gemini-mcp-redis`)
|
||||
- Official Redis 7 Alpine image
|
||||
- Automatic data persistence with Docker volume
|
||||
- Available at `redis:6379` within Docker network
|
||||
- Available at `localhost:6379` from host machine
|
||||
|
||||
2. **Gemini MCP Server** (`gemini-mcp-server`)
|
||||
- Built from local Dockerfile or pulled from GHCR
|
||||
- Automatically connects to Redis container
|
||||
- Your home directory mounted for file access
|
||||
- Configured with proper environment variables
|
||||
|
||||
**Key Benefits:**
|
||||
- 🔄 **Automatic Service Discovery**: No IP configuration needed
|
||||
- 💾 **Data Persistence**: Redis data survives container restarts
|
||||
- 🛡️ **Isolation**: Services run in isolated containers
|
||||
- 🚀 **Easy Updates**: Pull latest images with one command
|
||||
|
||||
## 🎉 What's Next?
|
||||
|
||||
Once you're set up:
|
||||
|
||||
1. **Explore the tools**: Try each tool to understand their specialties
|
||||
2. **Read the main README**: [Full documentation](../README.md) has advanced usage patterns
|
||||
3. **Join discussions**: [GitHub Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions) for tips and tricks
|
||||
4. **Contribute**: Found a bug or want a feature? [Open an issue](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
1. **Conversation Threading**: Gemini remembers context across multiple interactions thanks to automatic Redis setup!
|
||||
|
||||
2. **File Analysis**: Point Gemini at entire directories: "Use gemini to analyze my entire ~/Projects/myapp for architectural improvements"
|
||||
|
||||
3. **Collaborative Workflows**: Combine tools: "Use gemini to analyze this code, then review it for security issues"
|
||||
|
||||
4. **Thinking Modes**: Control depth vs cost: "Use gemini with minimal thinking to quickly explain this function"
|
||||
|
||||
5. **Logs are your friend**: Always check `docker compose logs -f` if something seems wrong
|
||||
|
||||
---
|
||||
|
||||
**Need Help?**
|
||||
- 📖 [Full Documentation](../README.md)
|
||||
- 💬 [Community Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions)
|
||||
- 🐛 [Report Issues](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||
412
docs/user-guides/troubleshooting.md
Normal file
412
docs/user-guides/troubleshooting.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide helps you resolve common issues with the Gemini MCP Server.
|
||||
|
||||
## Quick Diagnostics
|
||||
|
||||
### Check System Status
|
||||
|
||||
```bash
|
||||
# Verify containers are running
|
||||
docker compose ps
|
||||
|
||||
# Check logs for errors
|
||||
docker compose logs -f
|
||||
|
||||
# Test API connectivity
|
||||
docker exec -it gemini-mcp-server python -c "import os; print('API Key set:', bool(os.getenv('GEMINI_API_KEY')))"
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### 1. "Connection failed" in Claude Desktop
|
||||
|
||||
**Symptoms:**
|
||||
- Claude Desktop shows "Connection failed" when trying to use Gemini tools
|
||||
- MCP server appears disconnected
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if containers are running
|
||||
docker compose ps
|
||||
|
||||
# Should show both containers as 'Up'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Containers not running:**
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
2. **Container name mismatch:**
|
||||
```bash
|
||||
# Check actual container name
|
||||
docker ps --format "{{.Names}}"
|
||||
|
||||
# Update Claude Desktop config if needed
|
||||
```
|
||||
|
||||
3. **Docker Desktop not running:**
|
||||
- Ensure Docker Desktop is started
|
||||
- Check Docker daemon status: `docker info`
|
||||
|
||||
### 2. "GEMINI_API_KEY environment variable is required"
|
||||
|
||||
**Symptoms:**
|
||||
- Server logs show API key error
|
||||
- Tools respond with authentication errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check .env file:**
|
||||
```bash
|
||||
cat .env | grep GEMINI_API_KEY
|
||||
```
|
||||
|
||||
2. **Update API key:**
|
||||
```bash
|
||||
nano .env
|
||||
# Change: GEMINI_API_KEY=your_actual_api_key
|
||||
|
||||
# Restart services
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
3. **Verify key is valid:**
|
||||
- Check [Google AI Studio](https://makersuite.google.com/app/apikey)
|
||||
- Ensure key has proper permissions
|
||||
|
||||
### 3. Redis Connection Issues
|
||||
|
||||
**Symptoms:**
|
||||
- Conversation threading not working
|
||||
- Error logs mention Redis connection failures
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check Redis container
|
||||
docker compose ps redis
|
||||
|
||||
# Test Redis connectivity
|
||||
docker exec -it gemini-mcp-redis redis-cli ping
|
||||
# Should return: PONG
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Start Redis container:**
|
||||
```bash
|
||||
docker compose up -d redis
|
||||
```
|
||||
|
||||
2. **Reset Redis data:**
|
||||
```bash
|
||||
docker compose down
|
||||
docker volume rm gemini-mcp-server_redis_data
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
3. **Check Redis logs:**
|
||||
```bash
|
||||
docker compose logs redis
|
||||
```
|
||||
|
||||
### 4. Tools Not Responding / Hanging
|
||||
|
||||
**Symptoms:**
|
||||
- Gemini tools start but never complete
|
||||
- Long response times
|
||||
- Timeout errors
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Check for memory/CPU constraints
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Restart services:**
|
||||
```bash
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
2. **Increase memory limits:**
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
gemini-mcp:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
```
|
||||
|
||||
3. **Check API rate limits:**
|
||||
- Verify your Gemini API quota
|
||||
- Consider using a paid API key for higher limits
|
||||
|
||||
### 5. File Access Issues
|
||||
|
||||
**Symptoms:**
|
||||
- "File not found" errors when using file paths
|
||||
- Permission denied errors
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check mounted directory
|
||||
docker exec -it gemini-mcp-server ls -la /workspace
|
||||
|
||||
# Verify file permissions
|
||||
ls -la /path/to/your/file
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use absolute paths:**
|
||||
```
|
||||
✅ /Users/yourname/project/file.py
|
||||
❌ ./file.py
|
||||
```
|
||||
|
||||
2. **Check file exists in mounted directory:**
|
||||
```bash
|
||||
# Files must be within WORKSPACE_ROOT (default: $HOME)
|
||||
echo $WORKSPACE_ROOT
|
||||
```
|
||||
|
||||
3. **Fix permissions (Linux):**
|
||||
```bash
|
||||
sudo chown -R $USER:$USER /path/to/your/files
|
||||
```
|
||||
|
||||
### 6. Port Conflicts
|
||||
|
||||
**Symptoms:**
|
||||
- "Port already in use" errors
|
||||
- Services fail to start
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check what's using port 6379
|
||||
lsof -i :6379
|
||||
netstat -tulpn | grep 6379
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Stop conflicting services:**
|
||||
```bash
|
||||
# If you have local Redis running
|
||||
sudo systemctl stop redis
|
||||
# or
|
||||
brew services stop redis
|
||||
```
|
||||
|
||||
2. **Use different ports:**
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
redis:
|
||||
ports:
|
||||
- "6380:6379"
|
||||
```
|
||||
|
||||
## Platform-Specific Issues
|
||||
|
||||
### Windows (WSL2)
|
||||
|
||||
**Common Issues:**
|
||||
- Docker Desktop WSL2 integration not enabled
|
||||
- File path format issues
|
||||
- Permission problems
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Enable WSL2 integration:**
|
||||
- Docker Desktop → Settings → Resources → WSL Integration
|
||||
- Enable integration for your WSL distribution
|
||||
|
||||
2. **Use WSL2 paths:**
|
||||
```bash
|
||||
# Run commands from within WSL2
|
||||
cd /mnt/c/Users/yourname/project
|
||||
./setup-docker.sh
|
||||
```
|
||||
|
||||
3. **File permissions:**
|
||||
```bash
|
||||
# In WSL2
|
||||
chmod +x setup-docker.sh
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
**Common Issues:**
|
||||
- Docker Desktop not allocated enough resources
|
||||
- File sharing permissions
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Increase Docker resources:**
|
||||
- Docker Desktop → Settings → Resources
|
||||
- Increase memory to at least 4GB
|
||||
|
||||
2. **File sharing:**
|
||||
- Docker Desktop → Settings → Resources → File Sharing
|
||||
- Ensure your project directory is included
|
||||
|
||||
### Linux
|
||||
|
||||
**Common Issues:**
|
||||
- Docker permission issues
|
||||
- systemd conflicts
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Docker permissions:**
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
# Log out and back in
|
||||
```
|
||||
|
||||
2. **Start Docker daemon:**
|
||||
```bash
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
```
|
||||
|
||||
## Advanced Troubleshooting
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable detailed logging:
|
||||
|
||||
```bash
|
||||
# In .env file
|
||||
LOG_LEVEL=DEBUG
|
||||
|
||||
# Restart with verbose output
|
||||
docker compose down && docker compose up
|
||||
```
|
||||
|
||||
### Container Debugging
|
||||
|
||||
Access container for inspection:
|
||||
|
||||
```bash
|
||||
# Enter MCP server container
|
||||
docker exec -it gemini-mcp-server bash
|
||||
|
||||
# Check Python environment
|
||||
python --version
|
||||
pip list
|
||||
|
||||
# Test Gemini API directly
|
||||
python -c "
|
||||
import google.generativeai as genai
|
||||
import os
|
||||
genai.configure(api_key=os.getenv('GEMINI_API_KEY'))
|
||||
model = genai.GenerativeModel('gemini-pro')
|
||||
print('API connection test successful')
|
||||
"
|
||||
```
|
||||
|
||||
### Network Debugging
|
||||
|
||||
Check container networking:
|
||||
|
||||
```bash
|
||||
# Inspect Docker network
|
||||
docker network ls
|
||||
docker network inspect gemini-mcp-server_default
|
||||
|
||||
# Test container communication
|
||||
docker exec -it gemini-mcp-server ping redis
|
||||
```
|
||||
|
||||
### Clean Reset
|
||||
|
||||
Complete environment reset:
|
||||
|
||||
```bash
|
||||
# Stop everything
|
||||
docker compose down -v
|
||||
|
||||
# Remove images
|
||||
docker rmi $(docker images "gemini-mcp-server*" -q)
|
||||
|
||||
# Clean setup
|
||||
./setup-docker.sh
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Resource Monitoring
|
||||
|
||||
```bash
|
||||
# Monitor container resources
|
||||
docker stats
|
||||
|
||||
# Check system resources
|
||||
htop # or top
|
||||
df -h # disk space
|
||||
```
|
||||
|
||||
### Optimization Tips
|
||||
|
||||
1. **Allocate adequate memory:**
|
||||
- Minimum: 2GB for Docker Desktop
|
||||
- Recommended: 4GB+ for large projects
|
||||
|
||||
2. **Use SSD storage:**
|
||||
- Docker volumes perform better on SSDs
|
||||
|
||||
3. **Limit context size:**
|
||||
- Use specific file paths instead of entire directories
|
||||
- Utilize thinking modes to control token usage
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Collect Debug Information
|
||||
|
||||
Before seeking help, collect:
|
||||
|
||||
```bash
|
||||
# System information
|
||||
docker --version
|
||||
docker compose --version
|
||||
uname -a
|
||||
|
||||
# Container status
|
||||
docker compose ps
|
||||
docker compose logs --tail=100
|
||||
|
||||
# Configuration
|
||||
cat .env | grep -v "GEMINI_API_KEY"
|
||||
```
|
||||
|
||||
### Support Channels
|
||||
|
||||
- 📖 [Documentation](../README.md)
|
||||
- 💬 [GitHub Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions)
|
||||
- 🐛 [Issue Tracker](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||
|
||||
### Creating Bug Reports
|
||||
|
||||
Include in your bug report:
|
||||
1. System information (OS, Docker version)
|
||||
2. Steps to reproduce
|
||||
3. Expected vs actual behavior
|
||||
4. Relevant log output
|
||||
5. Configuration (without API keys)
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- [Installation Guide](installation.md)
|
||||
- [Configuration Guide](configuration.md)
|
||||
Reference in New Issue
Block a user