gemini-cli-mcp 0.1.0

Gemini CLI MCP Server

gemini-cli-mcp Python Server

This directory contains the Python implementation of the gemini-cli-mcp server. It uses FastAPI to expose gemini-cli functionalities as MCP-compliant tools.

1. Features

This server exposes the following gemini-cli commands as MCP Tools:

• gemini_ask: Ask a question to the Gemini model.
• gemini_agent: Run a complex prompt with Gemini Agent in auto-execution (--yolo) mode.
• gemini_git_commit: Generate a conventional commit message from staged changes and perform a git commit.
• gemini_git_pr: Automatically commit, push, and create a Pull Request.
• gemini_git_diff: Summarize code changes using Gemini AI.

2. Technology Stack

Category	Technology
Language	Python 3.12+
Web Framework	FastAPI
Process Exec	asyncio.subprocess
CLI Framework	Typer (via mcp-cli)
Packaging	Poetry / pyproject.toml

3. Setup

Prerequisites

• Python 3.12 or higher.
• gemini-cli installed globally and accessible in your system's PATH.
• git installed and configured.

Installation

1. Navigate to the server_py directory:

   cd server_py
   

2. Install dependencies using uv (recommended) or pip:

   uv pip install -r requirements.txt
   # or
   pip install -r requirements.txt
   

Environment Variables

The server uses environment variables for configuration. You can set these in a .env file in the project root (/Users/hackme/workspace/ai/mcp-server/gemini-cli-mcp/.env) or directly in your environment.

• GEMINI_MODEL: Specifies the Gemini model to use (e.g., gemini-2.5-flash).
• GEMINI_ALL_FILES: Set to true to include all files in context (--all-files).
• GEMINI_SANDBOX: Set to true to enable sandbox mode (--sandbox).
• GEMINI_API_KEY: Your Gemini API key (required for Docker/server environments).
• PROJECT_ROOT: The root directory of your project (important for gemini-cli operations).
• QUERY_TIMEOUT: Timeout for gemini-cli commands in seconds.
• USE_SHELL: Set to true to execute gemini-cli commands via shell (defaults to false).
• DEBUG: Set to true to enable detailed logging to log/{date}.log.

4. Running the Server

The user can select the execution mode via a CLI flag.

• STDIO Mode: python main.py (for direct CLI interaction)
• HTTP Mode: uvicorn main:app --host 0.0.0.0 --port 8000 (for AI agent integration)

Docker

A Dockerfile is provided to build and run the server in a container.

1. Build the Image: From the project root, run:

   docker build -t gemini-cli-mcp-python -f server_py/Dockerfile .
   

2. Run the Container:

   # Using an .env file
   docker run --env-file ../.env -p 8000:8000 gemini-cli-mcp-python
   
   # Passing environment variables directly
   docker run -e GEMINI_API_KEY=your_api_key -p 8000:8000 gemini-cli-mcp-python
   

5. Packaging & Distribution

The package will be distributed on PyPI. The pyproject.toml file defines a script entry point for the gemini-cli-mcp command, which will be deployed using poetry build and twine.

CLI Usage

After installing the package via pip, you can use the CLI entry point:

$ gemini-cli-mcp

This will launch the server in STDIO mode. To run in HTTP mode, use:

$ gemini-cli-mcp --http

6. Tool Usage

The server acts as a smart wrapper around gemini-cli. It constructs and executes the appropriate gemini-cli command based on the MCP tool invocation.

For example:

• gemini_ask(question="What is AI?") translates to gemini ask --model {model} --all-files --sandbox --prompt "What is AI?"
• gemini_agent(prompt="Do something complex.") translates to gemini agent --model {model} --all-files --sandbox --yolo --prompt "Do something complex."

7. Logging

Set the DEBUG environment variable to true to enable detailed logging to server_py/log/{YYYY-MM-DD}.log.