open-gemini

Use your own signed-in Gemini web account from a local CLI, MCP server, or loopback HTTP bridge. It automates the Gemini web app through Chrome; it does not use the Gemini API and does not require a Google API key. Your Google account and plan determine which models and features are available. This project does not unlock paid features or quotas.

Requirements and setup

• Node.js 22 or later

• Google Chrome installed

• A Google account that can use Gemini

Clone the repository and install its locked dependencies:

git clone https://github.com/mkshaonexe/open-gemini.git
cd open-gemini
npm ci

Sign in once through the normal Chrome window that open-gemini opens, then check the account:

node bin/cli.js login
node bin/cli.js status
node bin/cli.js capabilities
node bin/cli.js models

After sign-in, ordinary commands launch Chrome headlessly using the saved profile. This is still a browser runtime: keep the profile available and do not open it in another Chrome process while open-gemini is using it.

Related MCP server: mcp-cli-gemini

CLI examples

node bin/cli.js ask "Explain this topic in three paragraphs"
node bin/cli.js ask "Summarize this file" --file ./report.pdf
node bin/cli.js ask "Make an image of a red fox in snow" --tool image
node bin/cli.js ask "Plan a short video about a solar eclipse" --tool video
node bin/cli.js ask "Compose a calm piano theme" --tool music
node bin/cli.js ask "Research recent battery recycling methods" --tool research
node bin/cli.js history --limit 10
node bin/cli.js conversation CONVERSATION_ID
node bin/cli.js usage

ask prints the answer text when present. Use call with JSON when you need the complete structured result, including media URLs or returned metadata:

node bin/cli.js call ask --json '{"prompt":"Make an image of a red fox in snow","tool":"image"}'

The --tool options are image, video, music, canvas, and research. Check capabilities and models for what the current account exposes. Availability can change with account, plan, location, device, and rollout.

MCP

For an MCP host that supports a local stdio server, add a server entry using the absolute path to this checkout:

{
  "mcpServers": {
    "open-gemini": {
      "command": "node",
      "args": ["/absolute/path/open-gemini/bin/cli.js", "mcp"]
    }
  }
}

Replace /absolute/path/open-gemini with the actual checkout directory. Configuration syntax varies by host, so translate this standard stdio server entry if needed. Complete node bin/cli.js login first. The MCP server exposes the methods in the account bridge, including gemini_status, gemini_capabilities, gemini_models, gemini_ask, history/conversation operations, memory operations, usage, and download. Destructive conversation or memory deletion requires confirm: true.

Claude, Codex, and other agents can use the same standard stdio MCP configuration when their host supports it. Hermes or OpenClaw can connect through standard MCP if the installed host supports MCP; otherwise use the CLI workflow in skills/open-gemini/SKILL.md. This repository does not install a host-specific plugin.

Long-running work and local HTTP bridge

For longer generation or research requests, start the server in a terminal:

node bin/cli.js serve

Then submit and poll a job from another terminal:

node bin/cli.js jobs start ask --json '{"prompt":"Research this topic","tool":"research"}'
node bin/cli.js jobs JOB_ID

The server remains attached to one Chrome runtime. Stop it with Ctrl-C. A timed-out request may still have completed in Gemini; inspect its conversation or job state before retrying to avoid duplicate work.

The HTTP API listens on 127.0.0.1 by default and requires a generated bearer key. Get the local key only when configuring a trusted local client:

node bin/cli.js key

Keep this key private. It authorizes local API access and is separate from Google account credentials. The HTTP bridge limits JSON request bodies to 1 MiB and keeps a bounded, in-memory job queue of up to 100 jobs. Job state is not durable storage. The optional OpenAI-compatible routes expose model listing and one non-streaming, plain-text user message. They do not support streaming, tool calls, other message roles, or generation parameters.

Configuration

Configuration is stored under ~/.open-gemini by default. Environment variables can override it:

npm link is optional if you want the local checkout’s open-gemini command on your PATH. The project is used from source; this README does not promise an npm registry installation.

Troubleshooting

• If login cannot open Chrome, install Chrome or set CHROME_PATH to its executable.

• If Gemini still shows a sign-in page, complete sign-in in the Chrome window opened by login, then run status again.

• If you see PROFILE_BUSY, another open-gemini process owns that profile. Use OPEN_GEMINI_URL to connect to its running server, or stop it before starting another command.

• If the Chrome debugging port is already in use, choose another OPEN_GEMINI_CDP_PORT.

• If a model or feature is unavailable, check capabilities, models, and usage; account eligibility and usage limits are controlled by Google.

See Gemini feature inventory and plans and limits for official references and scope notes.