Gemini Cli Slim

A thin, auditable MCP server wrapping the Gemini CLI.

PyPI version Python versions License: MIT CI

Why

Existing Gemini MCP servers tend to either hide the underlying CLI behind opaque parameters or hard-code the supported flags so new gemini CLI options require code changes. This project takes a different approach:

• Single file, ~290 lines — auditable in one sitting
• One third-party dependency (mcp) — minimal supply-chain surface
• Forward-compatible — any new or uncommon gemini CLI flag is reachable via extra_args without touching this server
• Configurable binary path — $GEMINI_CMD lets you swap or wrap the gemini binary
• Workspace-aware — first-class include_directories so you can analyze multiple repositories from one invocation
• Transparent — every invocation logs the exact argv to stderr

Installation

Requires the gemini CLI to be installed and on $PATH (or pointed to via $GEMINI_CMD).

# Run directly without installing
uvx gemini-cli-mcp-slim

# Install from PyPI
pip install gemini-cli-mcp-slim

# Run from GitHub HEAD
uvx --from git+https://github.com/tksfjt1024/gemini-cli-mcp-slim gemini-cli-mcp-slim

Usage as an MCP server

Claude Code

claude mcp add gemini-cli-mcp-slim uvx gemini-cli-mcp-slim

Or manually in ~/.claude.json:

{
  "mcpServers": {
    "gemini-cli-mcp-slim": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gemini-cli-mcp-slim"]
    }
  }
}

Other MCP clients

Any MCP-compatible client can launch the server via stdio:

uvx gemini-cli-mcp-slim

Tools

consult_gemini

Run a single Gemini CLI invocation with full forward-compatibility.

Parameter	Type	Description
query (required)	string	Prompt sent verbatim to the gemini CLI
directory (required)	string	Working directory (gemini cwd, defines the default workspace root)
model	string	Model alias (flash, pro) or full model id
approval_mode	enum	default / auto_edit / yolo / plan
include_directories	string[]	Extra workspace directories (mapped to gemini --include-directories)
yolo	bool	Pass --yolo (auto-approve all)
sandbox	bool	Pass --sandbox
extra_args	string[]	Raw CLI flags appended verbatim. Use to access new/uncommon gemini flags
env	object	Extra environment variables for the gemini subprocess
timeout_seconds	int	Subprocess timeout in seconds (default 600)

consult_gemini_with_files

Same parameters as consult_gemini plus a files: string[] parameter. File paths are appended to the prompt as @path tokens (gemini's file reference syntax). Absolute paths inside directory are converted to relative @-paths.

web_search

Convenience wrapper that prepends a "use your built-in web search" instruction to the query.

Configuration

Environment variable	Default	Purpose
GEMINI_CMD	gemini	Path to the gemini CLI binary
GEMINI_CLI_MCP_SLIM_TIMEOUT	600	Default subprocess timeout in seconds
GEMINI_CLI_MCP_SLIM_LOG_LEVEL	INFO	Logging level for stderr diagnostics

Cross-repository analysis example

The killer feature: analyze multiple repositories from a single MCP invocation.

{
  "name": "consult_gemini",
  "arguments": {
    "query": "Compare the API surface between these services",
    "directory": "/path/to/service-a",
    "include_directories": [
      "/path/to/service-b",
      "/path/to/service-c"
    ],
    "model": "flash",
    "approval_mode": "plan"
  }
}

This launches gemini with --include-directories=/path/to/service-b,/path/to/service-c, giving the model read access to all three workspaces in one session.

Forward-compatibility example

If a future gemini CLI release adds a new flag (say --super-mode), you can use it immediately without updating this server:

{
  "name": "consult_gemini",
  "arguments": {
    "query": "...",
    "directory": "...",
    "extra_args": ["--super-mode", "--some-other-new-flag"]
  }
}

Comparison with alternatives

Project	Lines	Deps	include_directories	extra_args passthrough
gemini-cli-mcp-slim (this)	~290	1 (mcp)	yes	yes
eLyiN/gemini-bridge	~400	1 (mcp)	no	no
jamubc/gemini-mcp-tool	(TS)	many	no	partial

Development

# Install dev dependencies
pip install -e ".[test,dev]"

# Lint
ruff check .

# Test
pytest

License

MIT © tksfjt1024