# Gemini CLI MCP Server

An MCP (Model Context Protocol) server that wraps the Gemini CLI, exposing it over both stdio and SSE (Server-Sent Events) transports.

## Overview

This server allows remote clients to execute Gemini CLI commands through the MCP protocol. It can run as:
- **Local stdio server** (`server.py`) - for direct MCP client integration
- **Network SSE server** (`server_sse.py`) - for remote network access on port 8601

## Features

- **Dual Transport**: Supports both stdio (local) and SSE (network) transports
- **Gemini CLI Integration**: Executes prompts through the Gemini CLI
- **ANSI Stripping**: Cleans terminal escape codes from output
- **Systemd Integration**: Runs as a persistent user service
- **Network Accessible**: Binds to `0.0.0.0` for external access
- **Session Management**: Resume previous sessions, list sessions
- **Extension Support**: List available Gemini CLI extensions
- **YOLO Mode**: Auto-approve actions for automated use

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Remote MCP Clients                       │
│              (Claude Desktop, other agents)                 │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP/SSE (port 8601)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Gemini CLI MCP Server                          │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  FastMCP Server                                       │  │
│  │  - /sse endpoint for SSE connections                  │  │
│  │  - /messages/ endpoint for message posting            │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                  │
│                          ▼                                  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  MCP Tools (12 tools)                                 │  │
│  │  - run_gemini(): Execute prompts with full options    │  │
│  │  - gemini_resume(): Resume previous sessions          │  │
│  │  - gemini_list_sessions(): List available sessions    │  │
│  │  - gemini_list_extensions(): List CLI extensions      │  │
│  │  - gemini_version(): Get CLI version                  │  │
│  │  - gemini_delete_session(): Delete a session          │  │
│  │  - gemini_json(): Get JSON formatted output           │  │
│  │  - gemini_with_context(): Include files/dirs          │  │
│  │  - gemini_shell(): Execute shell commands             │  │
│  │  - gemini_chat_save(): Save chat session              │  │
│  │  - gemini_help(): Get CLI help                        │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                  │
│                          ▼                                  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Gemini CLI                                           │  │
│  │  $ gemini "prompt" -o text [-m MODEL] [-y]            │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## Directory Structure

```
/home/ward/MCP/gemini_mcp_server/
├── README.md                 # This documentation
├── server.py                 # Original stdio server (for local use)
├── server_sse.py             # SSE transport server (for network use)
├── requirements.txt          # Python dependencies
├── pyproject.toml            # Project configuration
├── .gitignore                # Git ignore rules
└── venv/                     # Python virtual environment

/home/ward/.config/systemd/user/
└── gemini-mcp-server.service # Systemd service unit file
```

## Prerequisites

1. **Gemini CLI**: Ensure `gemini` is installed and in your PATH.
   ```bash
   npm install -g @google/gemini-cli
   ```

2. **Authentication**: You must be authenticated with Google/Gemini.
   ```bash
   gemini  # Follow the authentication prompts
   ```

3. **Python**: Python 3.10 or higher.

## Installation

### Quick Install

```bash
# Clone or navigate to the project directory
cd /home/ward/MCP/gemini_mcp_server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Test the installation
python -c "from server import gemini_version; print(gemini_version())"
```

### Full Installation with Systemd Service

```bash
# Step 1: Set up the project
cd /home/ward/MCP/gemini_mcp_server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Step 2: Create systemd service file
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gemini-mcp-server.service << 'EOF'
[Unit]
Description=Gemini CLI MCP Server (SSE)
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/ward/MCP/gemini_mcp_server
ExecStart=/home/ward/MCP/gemini_mcp_server/venv/bin/python server_sse.py
Restart=always
RestartSec=5
Environment=MCP_SERVER_HOST=0.0.0.0
Environment=MCP_SERVER_PORT=8601

[Install]
WantedBy=default.target
EOF

# Step 3: Enable and start the service
systemctl --user daemon-reload
systemctl --user enable gemini-mcp-server
systemctl --user start gemini-mcp-server

# Step 4: Verify it's running
systemctl --user status gemini-mcp-server
curl -I http://localhost:8601/sse
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_SERVER_HOST` | `0.0.0.0` | Host to bind to (SSE server only) |
| `MCP_SERVER_PORT` | `8601` | Port to listen on (SSE server only) |

### Network Settings

The SSE server is configured for external access:
- Binds to `0.0.0.0` (all interfaces)
- Port `8601`
- DNS rebinding protection disabled for external clients

## Usage

### Option 1: Local stdio Server

For direct MCP client integration (same machine):

```bash
python server.py
```

**MCP Client Configuration:**
```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "python",
      "args": ["/home/ward/MCP/gemini_mcp_server/server.py"]
    }
  }
}
```

### Option 2: Network SSE Server

For remote network access:

**Manual Start:**
```bash
cd /home/ward/MCP/gemini_mcp_server
source venv/bin/activate
python server_sse.py
```

**Background Start:**
```bash
venv/bin/python server_sse.py > /tmp/gemini-mcp.log 2>&1 &
```

### Option 3: Systemd Service (Recommended for SSE)

The SSE server can be configured as a systemd user service for automatic startup.

**Create the service file:**
```bash
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gemini-mcp-server.service << 'EOF'
[Unit]
Description=Gemini CLI MCP Server (SSE)
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/ward/MCP/gemini_mcp_server
ExecStart=/home/ward/MCP/gemini_mcp_server/venv/bin/python server_sse.py
Restart=always
RestartSec=5
Environment=MCP_SERVER_HOST=0.0.0.0
Environment=MCP_SERVER_PORT=8601

[Install]
WantedBy=default.target
EOF
```

**Service Management:**
```bash
# Reload systemd
systemctl --user daemon-reload

# Start the service
systemctl --user start gemini-mcp-server

# Stop the service
systemctl --user stop gemini-mcp-server

# Restart the service
systemctl --user restart gemini-mcp-server

# Check status
systemctl --user status gemini-mcp-server

# View logs
journalctl --user -u gemini-mcp-server -f

# Enable auto-start on boot
systemctl --user enable gemini-mcp-server

# Disable auto-start
systemctl --user disable gemini-mcp-server
```

## API Reference

### Endpoints (SSE Server)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sse` | GET | SSE connection endpoint for MCP clients |
| `/messages/` | POST | Message posting endpoint |

### MCP Tools

#### `run_gemini`

Execute a command or query using the Gemini CLI.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | The prompt or command to send to Gemini |
| `model` | string | No | `""` | Model to use (e.g., gemini-2.5-flash, gemini-2.0-flash-exp, gemini-1.5-pro) |
| `sandbox` | boolean | No | `false` | Run in sandbox mode (isolated environment for safety) |
| `yolo` | boolean | No | `true` | Auto-approve all actions (recommended for automated use) |
| `output_format` | string | No | `"text"` | Output format: 'text', 'json', or 'stream-json' |
| `debug` | boolean | No | `false` | Enable debug mode for verbose output |
| `include_directories` | string | No | `""` | Comma-separated list of additional directories to include |

**Returns:** String containing the Gemini CLI output with ANSI codes stripped.

**Example:**
```json
{
  "tool": "run_gemini",
  "arguments": {
    "prompt": "What is 2 + 2?",
    "model": "gemini-2.5-flash",
    "output_format": "text"
  }
}
```

#### `gemini_resume`

Resume a previous Gemini CLI session.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `session` | string | No | `"latest"` | Session to resume. Use "latest" or index number |
| `prompt` | string | No | `""` | Optional prompt to continue the conversation |

**Returns:** String containing the session response.

**Example:**
```json
{
  "tool": "gemini_resume",
  "arguments": {
    "session": "latest",
    "prompt": "Continue from where we left off"
  }
}
```

#### `gemini_list_sessions`

List available Gemini CLI sessions for the current project.

**Parameters:** None

**Returns:** String listing available sessions.

**Example:**
```json
{
  "tool": "gemini_list_sessions",
  "arguments": {}
}
```

#### `gemini_list_extensions`

List all available Gemini CLI extensions.

**Parameters:** None

**Returns:** String listing installed extensions.

**Example:**
```json
{
  "tool": "gemini_list_extensions",
  "arguments": {}
}
```

#### `gemini_version`

Get the Gemini CLI version information.

**Parameters:** None

**Returns:** String containing version information (e.g., "0.20.0").

**Example:**
```json
{
  "tool": "gemini_version",
  "arguments": {}
}
```

#### `gemini_delete_session`

Delete a Gemini CLI session by index number.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `session_index` | string | Yes | - | The index number of the session to delete |

**Returns:** String confirming deletion or error message.

**Example:**
```json
{
  "tool": "gemini_delete_session",
  "arguments": {
    "session_index": "1"
  }
}
```

#### `gemini_json`

Execute a Gemini prompt and return structured JSON output. Useful for programmatic parsing of responses.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | The prompt or command to send to Gemini |
| `model` | string | No | `""` | Optional model to use |
| `sandbox` | boolean | No | `false` | Whether to run in sandbox mode |
| `yolo` | boolean | No | `true` | Whether to auto-approve all actions |

**Returns:** JSON-formatted response from Gemini.

**Example:**
```json
{
  "tool": "gemini_json",
  "arguments": {
    "prompt": "List 3 programming languages as JSON array"
  }
}
```

#### `gemini_with_context`

Execute a Gemini prompt with specific file or directory context. Uses @ syntax to include file contents in the prompt.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | The prompt or command to send to Gemini |
| `files` | string | No | `""` | Comma-separated list of file paths to include (e.g., "src/main.py,README.md") |
| `directories` | string | No | `""` | Comma-separated list of directories to include |
| `model` | string | No | `""` | Optional model to use |
| `yolo` | boolean | No | `true` | Whether to auto-approve all actions |

**Returns:** String containing Gemini's response with file context.

**Example:**
```json
{
  "tool": "gemini_with_context",
  "arguments": {
    "prompt": "Explain this code",
    "files": "src/main.py,src/utils.py"
  }
}
```

#### `gemini_shell`

Execute a shell command through Gemini CLI using ! syntax. Gemini can observe the output and provide analysis.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `command` | string | Yes | - | Shell command to execute (without the ! prefix) |

**Returns:** String containing command output and Gemini's analysis.

**Example:**
```json
{
  "tool": "gemini_shell",
  "arguments": {
    "command": "ls -la"
  }
}
```

#### `gemini_chat_save`

Save the current Gemini chat session.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | string | No | `""` | Optional name for the saved session |

**Returns:** String confirming save status.

**Example:**
```json
{
  "tool": "gemini_chat_save",
  "arguments": {
    "name": "my-session"
  }
}
```

#### `gemini_help`

Get Gemini CLI help information and available commands.

**Parameters:** None

**Returns:** String containing CLI help output.

**Example:**
```json
{
  "tool": "gemini_help",
  "arguments": {}
}
```

## Client Configuration

### MCP Configuration File Locations

| Client | Configuration File Location |
|--------|----------------------------|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
| Claude Code | `~/.claude/settings.json` or project `.mcp.json` |
| Cline (VS Code) | VS Code settings or `~/.cline/mcp_settings.json` |

---

### Option 1: SSE Transport (Network/Remote Access) - RECOMMENDED

Use this for network access or when the server runs as a systemd service.

**Claude Desktop / Claude Code:**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "url": "http://localhost:8601/sse",
      "transport": "sse"
    }
  }
}
```

**Remote Server Access:**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "url": "http://192.168.1.100:8601/sse",
      "transport": "sse"
    }
  }
}
```

**Cline (VS Code Extension):**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "url": "http://localhost:8601/sse",
      "transport": "sse"
    }
  }
}
```

---

### Option 2: stdio Transport (Local/Direct)

Use this for local-only access without running a persistent service.

**Claude Desktop (with venv):**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "/home/ward/MCP/gemini_mcp_server/venv/bin/python",
      "args": ["/home/ward/MCP/gemini_mcp_server/server.py"]
    }
  }
}
```

**Claude Desktop (system Python):**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "python3",
      "args": ["/home/ward/MCP/gemini_mcp_server/server.py"],
      "cwd": "/home/ward/MCP/gemini_mcp_server"
    }
  }
}
```

**With Environment Variables:**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "/home/ward/MCP/gemini_mcp_server/venv/bin/python",
      "args": ["/home/ward/MCP/gemini_mcp_server/server.py"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}
```

---

### Option 3: Project-Specific Configuration

Create a `.mcp.json` file in your project root:

```json
{
  "mcpServers": {
    "gemini-cli": {
      "url": "http://localhost:8601/sse",
      "transport": "sse"
    }
  }
}
```

---

### Complete Configuration Examples

**Full Claude Desktop config with multiple MCP servers:**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "url": "http://localhost:8601/sse",
      "transport": "sse"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    }
  }
}
```

**Claude Code settings.json:**

```json
{
  "mcpServers": {
    "gemini-cli": {
      "url": "http://localhost:8601/sse",
      "transport": "sse"
    }
  }
}
```

---

### Verifying the Configuration

After adding the configuration, verify the MCP server is accessible:

```bash
# Check if the server is running
systemctl --user status gemini-mcp-server

# Test the SSE endpoint
curl -I http://localhost:8601/sse

# Expected response:
# HTTP/1.1 200 OK
# content-type: text/event-stream
```

Restart your MCP client (Claude Desktop, Claude Code, etc.) after updating the configuration.

## Troubleshooting

### Server won't start

1. **Check if port is in use:**
   ```bash
   ss -tlnp | grep 8601
   ```

2. **Kill existing process:**
   ```bash
   lsof -i :8601 | awk 'NR>1 {print $2}' | xargs kill
   ```

3. **Check logs:**
   ```bash
   journalctl --user -u gemini-mcp-server -n 50
   ```

### Connection refused

1. **Verify server is running:**
   ```bash
   systemctl --user status gemini-mcp-server
   ```

2. **Check firewall:**
   ```bash
   sudo ufw status
   sudo ufw allow 8601/tcp
   ```

3. **Test locally:**
   ```bash
   curl -I http://localhost:8601/
   ```

### Gemini CLI errors

1. **Verify CLI is installed:**
   ```bash
   which gemini
   gemini --version
   ```

2. **Test CLI directly:**
   ```bash
   gemini "Hello" -o text -y
   ```

## Security Considerations

**Warning**: This server exposes Gemini CLI over the network.

- The server uses YOLO mode (`-y`) by default for automated use
- Consider using a firewall to restrict access
- Consider using a reverse proxy with authentication for production use
- Be mindful of API costs when exposing to network

### Recommended Security Measures

1. **Firewall rules:**
   ```bash
   # Allow only specific IPs
   sudo ufw allow from 192.168.1.0/24 to any port 8601
   ```

2. **Reverse proxy with auth** (nginx example):
   ```nginx
   location /mcp/ {
       auth_basic "MCP Server";
       auth_basic_user_file /etc/nginx/.htpasswd;
       proxy_pass http://localhost:8601/;
   }
   ```

## Files Reference

### server.py

Original stdio transport server for local MCP client integration.

### server_sse.py

SSE transport server for network access. Configured to:
- Listen on `0.0.0.0:8601`
- Disable DNS rebinding protection
- Allow all hosts and origins

### requirements.txt

```
mcp[cli]
uvicorn
starlette
```

### Systemd Service File

Location: `/home/ward/.config/systemd/user/gemini-mcp-server.service`

```ini
[Unit]
Description=Gemini CLI MCP Server (SSE)
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/ward/MCP/gemini_mcp_server
ExecStart=/home/ward/MCP/gemini_mcp_server/venv/bin/python server_sse.py
Restart=always
RestartSec=5
Environment=MCP_SERVER_HOST=0.0.0.0
Environment=MCP_SERVER_PORT=8601

[Install]
WantedBy=default.target
```

## Deployment & Management Commands

### Quick Reference

```bash
# Start the server
systemctl --user start gemini-mcp-server

# Stop the server
systemctl --user stop gemini-mcp-server

# Restart the server
systemctl --user restart gemini-mcp-server

# Check server status
systemctl --user status gemini-mcp-server

# View live logs
journalctl --user -u gemini-mcp-server -f

# View last 50 log entries
journalctl --user -u gemini-mcp-server -n 50

# Enable auto-start on boot
systemctl --user enable gemini-mcp-server

# Disable auto-start on boot
systemctl --user disable gemini-mcp-server

# Reload service configuration after changes
systemctl --user daemon-reload
```

### Health Check Commands

```bash
# Verify server is listening
ss -tlnp | grep 8601

# Test SSE endpoint
curl -I http://localhost:8601/sse

# Test from remote host
curl -I http://<server-ip>:8601/sse
```

### Process Management

```bash
# Find server process
pgrep -f "server_sse.py"

# Get process details
ps aux | grep server_sse.py

# Force kill if unresponsive
pkill -f "server_sse.py"

# Check port usage
lsof -i :8601
```

### Log Analysis

```bash
# View all logs
journalctl --user -u gemini-mcp-server --no-pager

# Filter by time
journalctl --user -u gemini-mcp-server --since "1 hour ago"

# Export logs to file
journalctl --user -u gemini-mcp-server > /tmp/gemini-mcp-server.log
```

### Service Configuration

```bash
# Edit service file
nano ~/.config/systemd/user/gemini-mcp-server.service

# After editing, reload and restart
systemctl --user daemon-reload
systemctl --user restart gemini-mcp-server
```

## Port Registration

This service is registered in the system port log (`~/.claude/PORT-LOG.md`):

| Port | Service | Description |
|------|---------|-------------|
| 8601 | MCP SSE | Gemini CLI MCP Server with SSE transport |

## Comparison with Claude Code MCP Server

| Feature | Claude Code MCP Server | Gemini CLI MCP Server |
|---------|------------------------|------------------------|
| Port | 8600 | 8601 |
| CLI Tool | `claude` | `gemini` |
| Primary Tool | `run_claude` | `run_gemini` |
| Auto-Approve Flag | `--dangerously-skip-permissions` | `-y` (yolo mode) |
| Session Support | No | Yes (`gemini_resume`, `gemini_list_sessions`) |
| Extensions | No | Yes (`gemini_list_extensions`) |
| Transport | stdio, SSE | stdio, SSE |

## License

MIT License

## Author

Created with Claude Code

## Changelog

### v1.1.0 (2025-12-10)

- Enhanced `run_gemini` with new parameters:
  - `output_format`: Choose between text, json, or stream-json
  - `debug`: Enable verbose debug output
  - `include_directories`: Include additional directories in context
- Added new tools based on official documentation:
  - `gemini_delete_session`: Delete sessions by index
  - `gemini_json`: Get structured JSON output
  - `gemini_with_context`: Include files/directories using @ syntax
  - `gemini_shell`: Execute shell commands with ! syntax
  - `gemini_chat_save`: Save chat sessions
  - `gemini_help`: Get CLI help information
- Now supports 12 MCP tools total
- Improved error handling and validation

### v1.0.0 (2025-12-10)

- Initial release
- stdio and SSE transport support
- Gemini CLI integration with `run_gemini` tool
- Session management with `gemini_resume` and `gemini_list_sessions` tools
- Extension listing with `gemini_list_extensions` tool
- Version info with `gemini_version` tool
- ANSI code stripping
- Comprehensive documentation
- Systemd service template