Skip to main content
Glama
wminson

Gemini CLI MCP Server

by wminson
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wminson/gemini_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server