How-to

Connect Gemini CLI

Point Gemini CLI at one local LightNow Proxy. From there, use LightNow to choose the MCP servers Gemini should see, keep secrets out of local config, and inspect tool usage in one place.

Gemini CLI setupGemini CLI starts one LightNow Proxy; LightNow manages the server set

AI clientGemini CLIreads JSON mcpServers from ~/.gemini/settings.json

stdio

LightNow Local Proxylightnow-proxyserves the Runtime Profile as one Gemini MCP server

LightNow

LightNowConfig + Analyzeprofile, workspace, policy, events and tool usage

Prepare the profile first

Gemini CLI does not import existing MCP entries today. Add the servers Gemini should use to a Runtime Profile in LightNow before syncing the local settings file.

Fast setup

1

Install LightNow

Install the CLI and the local proxy on this machine.

2

Sign in

Sign in so LightNow can use your account and selected workspace.

3

Prepare the Runtime Profile

Add the MCP servers Gemini should use to the LightNow Runtime Profile first.

4

Sync Gemini CLI

Replace direct MCP entries with one LightNow Proxy entry.

5

Restart Gemini CLI

Start a fresh Gemini CLI session so the MCP server list is loaded again.

Recommended for macOS

brew tap lightnow-ai/tap
brew install lightnow-cli lightnow-proxy
lightnow login
lightnow sync --client gemini-cli --local-proxy

Windows or Linux

Windows

py -m pip install --user pipx
py -m pipx ensurepath
py -m pipx install lightnow-cli
py -m pipx install lightnow-proxy
lightnow login
lightnow sync --client gemini-cli --local-proxy

Linux

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install lightnow-cli
python3 -m pipx install lightnow-proxy
lightnow login
lightnow sync --client gemini-cli --local-proxy

Runtime Profile

LightNow uses the default Runtime Profile unless you pass --profile <name>.

Config files

These are the files LightNow touches for Gemini CLI:

Gemini settings

~/.gemini/settings.json

Local Proxy config

~/.lightnow/lightnow-proxy/gemini-cli.yaml

What gets written

Gemini CLI reads MCP servers from JSON. After sync, that JSON contains one top-level mcpServers.LightNow entry:

~/.gemini/settings.json

{
  "mcpServers": {
    "LightNow": {
      "command": "lightnow-proxy",
      "args": [
        "--config",
        "~/.lightnow/lightnow-proxy/gemini-cli.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

When LightNow can resolve the full lightnow-proxy path, it writes the absolute path. The proxy YAML stores the Gemini CLI client name, stdio transport, selected Runtime Profile, workspace context, policy settings, telemetry preference and secret-resolution mode. Gemini CLI does not receive the commands, URLs or secret values for every server in the profile.

Existing Gemini settings

When Local Proxy mode replaces direct MCP entries, LightNow removes the top-level JSON mcpServers and servers sections, then adds LightNow. Other Gemini settings stay in the file. Existing values such as selectedAuthType and theme remain in ~/.gemini/settings.json.

If Gemini already has direct MCP entries, model the useful upstreams in a LightNow Runtime Profile before running sync. That gives Gemini one local LightNow entry while keeping upstream commands, URLs, headers and secrets out of the client settings file.

Team rollout

For a managed team rollout, switch to the organization context first, then let policy drive the sync:

Use LightNow-managed client policy

lightnow context --tenant acme
lightnow sync --client gemini-cli --from-settings
lightnow config-status --client gemini-cli --json

--from-settings lets LightNow choose the profile, telemetry setting, managed clients and unmanaged-entry policy for Gemini CLI. Use it after the organization profile is ready and the pilot setup works as expected.

Related guides

Integrations and Runtime Profiles

Prepare the Runtime Profile Gemini CLI will consume through the Local Proxy.

Debug Local Proxy

Use config-status, proxy health JSON and redacted protocol capture when Gemini CLI cannot see tools.

MCP client support

Compare client targets, default paths, Local Proxy support and import support across Codex, Claude, Cursor, VS Code, Antigravity, Gemini CLI and others.