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