Skip to content

wminson/gemini_mcp_server

BranchesTags

Repository files navigation

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.

    npm install -g @google/gemini-cli

  2. Authentication: You must be authenticated with Google/Gemini.

    gemini  # Follow the authentication prompts

  3. Python: Python 3.10 or higher.

Installation

Quick Install

# 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

# 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):

python server.py

MCP Client Configuration:

{
  "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:

cd /home/ward/MCP/gemini_mcp_server
source venv/bin/activate
python server_sse.py

Background Start:

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:

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:

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

{
  "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:

{
  "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:

{
  "tool": "gemini_list_sessions",
  "arguments": {}
}

gemini_list_extensions

List all available Gemini CLI extensions.

Parameters: None

Returns: String listing installed extensions.

Example:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Remote Server Access:

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

Cline (VS Code Extension):

{
  "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):

{
  "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):

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

With Environment Variables:

{
  "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:

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

Complete Configuration Examples

Full Claude Desktop config with multiple MCP servers:

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

Claude Code settings.json:

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

Verifying the Configuration

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

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

    ss -tlnp | grep 8601

  2. Kill existing process:

    lsof -i :8601 | awk 'NR>1 {print $2}' | xargs kill

  3. Check logs:

    journalctl --user -u gemini-mcp-server -n 50

Connection refused

  1. Verify server is running:

    systemctl --user status gemini-mcp-server

  2. Check firewall:

    sudo ufw status
sudo ufw allow 8601/tcp

  3. Test locally:

    curl -I http://localhost:8601/

Gemini CLI errors

  1. Verify CLI is installed:

    which gemini
gemini --version

  2. Test CLI directly:

    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:

    # Allow only specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 8601

  2. Reverse proxy with auth (nginx example):

    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

[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

# 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

# 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

# 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

# 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

# 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

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages