gemini-mcp-cli 1.0.0__py3-none-any.whl

gemini_mcp_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: gemini-mcp-cli
+Version: 1.0.0
+Summary: FastMCP server wrapping Google's Gemini CLI — use Gemini models from any MCP client
+Project-URL: Homepage, https://github.com/jxsprt/gemini-mcp-server
+Project-URL: Repository, https://github.com/jxsprt/gemini-mcp-server
+Project-URL: Issues, https://github.com/jxsprt/gemini-mcp-server/issues
+Author-email: Jaspreet Singh <jaspreetsinghintp@gmail.com>
+License: MIT
+Keywords: fastmcp,gemini,gemini-cli,mcp,mcp-server
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Gemini CLI MCP Server
+
+[![CI](https://github.com/jxsprt/gemini-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/jxsprt/gemini-mcp-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/badge/PyPI-pip%20install%20gemini--mcp--server-blue)](https://pypi.org/project/gemini-mcp-server/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![PR to Hermes Agent](https://img.shields.io/badge/PR-Hermes%20Agent-%23NouResearch?label=PR)](https://github.com/NousResearch/hermes-agent/pull/22878)
+
+A lightweight [FastMCP](https://gofastmcp.com) server that wraps Google's [Gemini CLI](https://github.com/google-gemini/gemini-cli) as MCP tools. Works with any MCP client — Hermes Agent, Claude Code, Claude Desktop, Cursor, etc.
+
+## Prerequisites
+
+- **Node.js** — for the Gemini CLI
+- **Python 3.11+** — for the MCP server
+- **Gemini CLI** — installed and authenticated
+
+```bash
+npm install -g @google/gemini-cli
+gemini --version          # Verify install
+gemini                    # Run once to complete OAuth login
+```
+
+## Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/jxsprt/gemini-mcp-server.git
+cd gemini-mcp-server
+
+# Create venv and install deps
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+## Configuration
+
+Add to your MCP client's config:
+
+### Hermes Agent (`~/.hermes/config.yaml`)
+
+```yaml
+mcp_servers:
+  gemini-cli:
+    command: "/path/to/gemini-mcp-server/.venv/bin/python3"
+    args: ["/path/to/gemini-mcp-server/server.py"]
+    timeout: 240
+```
+
+Restart your Hermes gateway. Tools will be available as `mcp_gemini_cli_*`.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "gemini-cli": {
+      "command": "/path/to/gemini-mcp-server/.venv/bin/python3",
+      "args": ["/path/to/gemini-mcp-server/server.py"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+fastmcp install claude-code /path/to/gemini-mcp-server/server.py
+```
+
+### Cursor
+
+```bash
+fastmcp install cursor /path/to/gemini-mcp-server/server.py -e .
+```
+
+## Tools
+
+### `gemini_prompt`
+
+Send any prompt to Gemini CLI non-interactively. Supports model selection and JSON output.
+
+**Safe by default** — uses `--approval-mode auto-edit` (auto-approves file edits, prompts for shell). Pass `dangerous=true` for full `yolo` mode.
+
+```python
+gemini_prompt(prompt="Explain TCP handshake", model="gemini-2.5-flash")
+gemini_prompt(prompt="Refactor this module", dangerous=True)     # full auto-approval
+```
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `prompt` | string | ✅ | — | Prompt text (max ~100K chars) |
+| `model` | string | ❌ | CLI default | Model name (e.g., `gemini-3-flash-preview`) |
+| `output_format` | string | ❌ | `text` | `text`, `json`, or `stream-json` |
+| `dangerous` | bool | ❌ | `false` | Use `--approval-mode yolo` (auto-approves shell) |
+
+### `gemini_plan`
+
+Read-only audit and review mode. Uses `--approval-mode plan` — **guarantees no file mutations or shell execution**. Safe for whole-repo analysis and code reviews.
+
+```python
+gemini_plan(prompt="Review this auth module for security issues")
+```
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `prompt` | string | ✅ | — | Analysis question or review request |
+| `model` | string | ❌ | CLI default | Gemini model |
+| `include_directories` | string | ❌ | — | Comma-separated additional dirs |
+
+### `gemini_version`
+
+Returns the installed Gemini CLI version.
+
+```python
+gemini_version()  # → "0.41.2"
+```
+
+## Verification
+
+```bash
+cd /path/to/gemini-mcp-server
+.venv/bin/python -c "
+import server
+print('Version:', server.gemini_version())
+print('Prompt:', server.gemini_prompt('Say hello in one word'))
+print('Plan:', server.gemini_plan('What tools does this server have?'))
+"
+```
+
+## How It Works
+
+The server shells out to `gemini -p "prompt" --approval-mode yolo` for each tool call. It does NOT use the Google Gen AI Python SDK — it goes through the Gemini CLI binary (OAuth-authenticated).
+
+**Key design decisions:**
+- **Stdio transport** — runs as a subprocess of your MCP client
+- **No hardcoded paths** — discovers `gemini` on PATH
+- **No API keys in config** — uses the CLI's existing OAuth session
+- **Retry-friendly** — generous timeouts (120s default, 240s for plan mode) to handle Gemini's capacity retries
+
+## Notes
+
+- **Capacity errors**: Gemini's reasoning models can hit rate limits. The CLI retries up to 7 times with backoff. If it fails, try again later or use a different model.
+- **Plan mode is safe**: `--approval-mode plan` explicitly prevents the agent from writing files or executing shell commands. Read-only, guaranteed.
+- **1M token context**: Gemini CLI supports the full 1M token context window of Gemini models.
+
+## License
+
+MIT

gemini_mcp_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+gemini_mcp_server/__init__.py,sha256=EYzg5PB1KqwRyAaQ7-cR3UdyragGjktce-zvWbX5U2M,225
+gemini_mcp_server/__main__.py,sha256=dHOSZ1BdFFbUPYxDhEGuiU5i_GmkxtEZW8olFqr8CIU,129
+gemini_mcp_server/server.py,sha256=nwd2s1f-6jxrhTM0P-WJTV0Jo7M6q__ArNcsi_HERZs,9282
+gemini_mcp_cli-1.0.0.dist-info/METADATA,sha256=buaUIkYTShMKN0XbA-QJ-NCzGZ3NzEimLwheNuvlmvU,6010
+gemini_mcp_cli-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gemini_mcp_cli-1.0.0.dist-info/entry_points.txt,sha256=bWFu_7C87aMqg0wsNdX1vq20Ww77eYpYjHZu2UxqVcA,54
+gemini_mcp_cli-1.0.0.dist-info/RECORD,,

gemini_mcp_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gemini_mcp_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gemini-mcp = gemini_mcp_server:main

gemini_mcp_server/__init__.py

@@ -0,0 +1,5 @@
+"""gemini-mcp-server — FastMCP server wrapping Google's Gemini CLI."""
+
+from .server import mcp, gemini_prompt, gemini_plan, gemini_version, main
+
+__all__ = ["mcp", "gemini_prompt", "gemini_plan", "gemini_version", "main"]

gemini_mcp_server/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m gemini_mcp_server"""
+
+from gemini_mcp_server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

gemini_mcp_server/server.py

@@ -0,0 +1,263 @@
+"""
+gemini-mcp-server — FastMCP server wrapping Google's Gemini CLI.
+
+Exposes Gemini CLI as MCP tools consumable by any MCP client
+(Hermes Agent, Claude Code, Claude Desktop, Cursor, etc.).
+
+Powered by FastMCP (https://gofastmcp.com).
+
+Tools:
+  - gemini_prompt    → Send a prompt to Gemini CLI (non-interactive, full power)
+  - gemini_plan      → Read-only audit/review mode (--approval-mode plan)
+  - gemini_version   → Get Gemini CLI version
+"""
+
+import logging
+import os
+import shutil
+import subprocess
+from typing import Optional
+
+from fastmcp import FastMCP
+
+# ── Logging ────────────────────────────────────────────────────────────────
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    stream=__import__("sys").stderr,
+)
+logger = logging.getLogger("gemini-mcp")
+
+# ── Server ─────────────────────────────────────────────────────────────────
+
+mcp = FastMCP("Gemini CLI MCP Server")
+
+# ── Configuration (env vars with sensible defaults) ────────────────────────
+
+_GEMINI_CLI_PATH = os.environ.get("GEMINI_CLI_PATH")
+DEFAULT_TIMEOUT = int(os.environ.get("GEMINI_TIMEOUT", "120"))
+PLAN_TIMEOUT = int(os.environ.get("GEMINI_PLAN_TIMEOUT", "240"))
+MAX_PROMPT_LENGTH = int(os.environ.get("GEMINI_MAX_PROMPT", "100000"))
+HTTP_ENABLED = os.environ.get("GEMINI_MCP_HTTP", "").lower() in ("1", "true", "yes")
+
+
+def _get_gemini_bin() -> str:
+    """Locate the gemini CLI binary. Returns full path or raises RuntimeError."""
+    if _GEMINI_CLI_PATH:
+        path = _GEMINI_CLI_PATH
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+        raise RuntimeError(
+            f"GEMINI_CLI_PATH set to '{path}' but file not found or not executable. "
+            "Fix the path or unset it to auto-discover."
+        )
+    path = shutil.which("gemini")
+    if path is None:
+        raise RuntimeError(
+            "Gemini CLI not found on PATH. Install it with: npm install -g @google/gemini-cli, "
+            "or set the GEMINI_CLI_PATH environment variable."
+        )
+    return path
+
+
+# ── Helper ─────────────────────────────────────────────────────────────────
+
+
+def _run_gemini(args: list[str], timeout: int = DEFAULT_TIMEOUT) -> dict:
+    """Run `gemini <args>` and return structured result.
+
+    Returns dict with keys: success, output, error.
+    """
+    gemini_bin = _get_gemini_bin()
+    cmd = [gemini_bin] + args
+    logger.info("Running: %s", " ".join(cmd))
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        stdout = result.stdout.strip()
+        stderr = result.stderr.strip()
+
+        if result.returncode != 0:
+            logger.warning("Non-zero exit %d: %s", result.returncode, stderr[:200])
+            return {
+                "success": False,
+                "output": stdout,
+                "error": stderr or f"Exit code {result.returncode}",
+            }
+
+        logger.info("Success (%d chars)", len(result.stdout))
+        return {"success": True, "output": stdout, "error": None}
+
+    except subprocess.TimeoutExpired:
+        logger.warning("Timed out after %ds", timeout)
+        return {
+            "success": False,
+            "output": "",
+            "error": f"Command timed out after {timeout}s",
+        }
+    except FileNotFoundError:
+        msg = f"Gemini CLI not found at {gemini_bin}"
+        logger.error(msg)
+        return {"success": False, "output": "", "error": msg}
+    except Exception as e:
+        logger.exception("Unexpected error")
+        return {"success": False, "output": "", "error": str(e)}
+
+
+# ── Tools ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool(
+    name="gemini_prompt",
+    description=(
+        "Send a prompt to Gemini CLI in non-interactive mode. "
+        "The full power of Gemini models — coding, research, Q&A, analysis. "
+        "Supports optional model selection and output format."
+    ),
+)
+def gemini_prompt(
+    prompt: str,
+    model: Optional[str] = None,
+    output_format: Optional[str] = None,
+    dangerous: bool = False,
+) -> str:
+    """Execute a prompt via Gemini CLI.
+
+    By default uses --approval-mode auto-edit (safe for file edits in working dir).
+    Pass dangerous=True to use --approval-mode yolo (auto-approves ALL actions
+    including arbitrary shell commands).
+
+    Args:
+        prompt: The prompt text to send (max ~100K chars).
+        model: Gemini model to use (e.g., gemini-3-flash-preview, gemini-2.5-pro).
+               Defaults to gemini CLI's built-in default.
+        output_format: 'text' (default), 'json', or 'stream-json'.
+                       JSON includes token/cost stats in the envelope.
+        dangerous: If True, uses --approval-mode yolo (auto-approves shell cmds).
+                   Defaults to False (--approval-mode auto-edit).
+
+    Returns:
+        Gemini CLI output as a string.
+    """
+    if len(prompt) > MAX_PROMPT_LENGTH:
+        prompt = prompt[:MAX_PROMPT_LENGTH]
+
+    approval = "yolo" if dangerous else "auto_edit"
+    args = ["-p", prompt, "--approval-mode", approval]
+
+    if model:
+        args += ["-m", model]
+    if output_format:
+        args += ["-o", output_format]
+
+    result = _run_gemini(args, timeout=DEFAULT_TIMEOUT)
+
+    if result["success"]:
+        return result["output"] or "(empty response)"
+    else:
+        error_msg = result["error"] or "unknown error"
+        return f"Error: {error_msg}"
+
+
+@mcp.tool(
+    name="gemini_plan",
+    description=(
+        "Read-only audit, code review, and research via Gemini CLI. "
+        "Uses --approval-mode plan which guarantees NO file mutations or shell execution. "
+        "Safe for whole-repo analysis, code reviews, vulnerability assessments, "
+        "architecture audits, and deep research."
+    ),
+)
+def gemini_plan(
+    prompt: str,
+    model: Optional[str] = None,
+    include_directories: Optional[str] = None,
+) -> str:
+    """Run Gemini CLI in read-only plan mode — no mutations possible.
+
+    Args:
+        prompt: Analysis question or review request.
+        model: Gemini model (optional, defaults to gemini CLI default).
+        include_directories: Comma-separated additional dirs to include in workspace.
+                             Only includes subdirectories of the current working directory
+                             for safety.
+
+    Returns:
+        Gemini CLI's analysis/plan output.
+    """
+    if len(prompt) > MAX_PROMPT_LENGTH:
+        prompt = prompt[:MAX_PROMPT_LENGTH]
+
+    args = ["-p", prompt, "--approval-mode", "plan"]
+
+    if model:
+        args += ["-m", model]
+
+    # Validate include_directories — restrict to CWD subdirectories
+    if include_directories:
+        cwd = os.getcwd()
+        validated = []
+        for d in include_directories.split(","):
+            d = d.strip()
+            abs_d = os.path.abspath(os.path.join(cwd, d)) if not os.path.isabs(d) else d
+            if abs_d.startswith(cwd.rstrip("/") + "/") or abs_d == cwd:
+                validated.append(d)
+            else:
+                logger.warning("Ignored out-of-workspace path: %s", d)
+        if validated:
+            args += ["--include-directories", ",".join(validated)]
+
+    result = _run_gemini(args, timeout=PLAN_TIMEOUT)
+
+    if result["success"]:
+        return result["output"] or "(empty response)"
+    else:
+        error_msg = result["error"] or "unknown error"
+        return f"Error: {error_msg}"
+
+
+@mcp.tool(
+    name="gemini_version",
+    description="Get the installed Gemini CLI version.",
+)
+def gemini_version() -> str:
+    """Get Gemini CLI version info."""
+    try:
+        gemini_bin = _get_gemini_bin()
+        result = subprocess.run(
+            [gemini_bin, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        output = (result.stdout or result.stderr or "").strip()
+        return output or "(no version info)"
+    except subprocess.TimeoutExpired:
+        return "Error: Command timed out after 10s"
+    except RuntimeError as e:
+        return f"Error: {e}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+# ── Entrypoint ─────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    """CLI entry point for pip-installed package."""
+    if HTTP_ENABLED:
+        logger.info("Starting HTTP transport on port 8000")
+        mcp.run(transport="http")
+    else:
+        logger.info("Starting stdio transport")
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()