Configuring MCP In Gemini Cli

Google's Gemini CLI added MCP support not long after Anthropic open-sourced the protocol, and its implementation is close enough to Claude Code's that a lot of the muscle memory transfers directly — same mcpServers JSON key, similar scoping. The differences that do exist are worth knowing precisely, because they're exactly the kind of thing that silently breaks a config you copy-pasted from a Claude Code project.

Installing Gemini CLI and Preparing for MCP Integration

Install via npm (Node 18+) or Homebrew:

npm install -g @google/gemini-cli
brew install gemini-cli

gemini --version

Authenticate with a Google account (free tier available with rate limits) or an API key from Google AI Studio:

gemini
export GEMINI_API_KEY=AIza...

Confirm the base install works before adding MCP servers:

gemini -p "What is 2+2?"

As with the other tools, test any local MCP server binary standalone first:

npx -y @modelcontextprotocol/server-filesystem ~/projects

Gemini CLI resolves project-scoped config from the directory you launch it in, walking up to find a .gemini folder or a git root — the same directory-resolution model as Claude Code, which is one of the easier things to keep straight when supporting a team using both tools.

Tips
- If your org uses Google Workspace SSO, the OAuth login flow for Gemini CLI can require a separate consent screen approval from a Workspace admin for third-party CLI tools — check this before assuming a failed login is a config issue.
- Free-tier Gemini API rate limits (as of current releases, roughly 60 requests/minute on gemini-2.5-flash, lower on pro models) apply to MCP tool-calling turns too — a chatty agent looping through several tool calls per response burns through that quota fast.

Configuring MCP Servers in Gemini CLI's settings.json

Project-scoped config: .gemini/settings.json at the repo root. User-scoped config: ~/.gemini/settings.json. The key name and shape are deliberately close to Claude Code's:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "sentry": {
      "httpUrl": "https://mcp.sentry.dev/sse"
    }
  }
}

Two concrete differences from Claude Code's schema that will bite you if you copy config over verbatim:

1. Remote server key is httpUrl or url depending on transport, not type + url. Gemini CLI infers stdio vs. remote from which keys are present rather than an explicit type discriminator. For SSE specifically, use url; for a plain HTTP-streamable endpoint, httpUrl. Getting this backwards produces a connection failure with a not-very-descriptive error.

{
  "mcpServers": {
    "sse-server": {
      "url": "https://mcp.example.com/sse"
    },
    "http-server": {
      "httpUrl": "https://mcp.example.com/mcp"
    }
  }
}

1. Env var interpolation uses $VAR or ${VAR}, both work, but Gemini CLI additionally supports a .env file at the project root loaded automatically — a convenience Claude Code doesn't have out of the box. Drop secrets into .gemini/.env (gitignored) instead of exporting them in your shell every session:

GITHUB_TOKEN=ghp_xxxxxxxxxxxx

You can also set a timeout per server (milliseconds) and a trust flag that, when true, skips the per-call tool confirmation prompt for that specific server — useful for read-only servers you've vetted, risky for anything with write access:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "timeout": 10000,
      "trust": true
    }
  }
}

Tips
- Don't blanket-set trust: true across all servers just to stop confirmation prompts — reserve it for read-only, low-blast-radius tools and keep confirmation on for anything that writes to a database, filesystem, or ticketing system.
- Drop team-shared, non-secret env defaults into .gemini/.env.example committed to the repo, and keep the real .gemini/.env gitignored — this mirrors the .env/.env.example convention most teams already use for app config.

Using Gemini CLI with Local and Remote MCP Servers

Local stdio servers behave identically to the other tools — Gemini CLI spawns the process, communicates over stdin/stdout, and tears it down when the session ends. Nothing Gemini-specific there beyond the config shape already shown.

Remote servers are where Gemini CLI's Google-ecosystem integration shows up. Google publishes first-party MCP-compatible tooling for some of its own services, and OAuth-based remote servers (as opposed to static bearer tokens) get handled through a gemini mcp auth <name> flow rather than manual token pasting:

gemini mcp auth notion

List and inspect configured servers from the CLI directly, without entering an interactive session:

gemini mcp list

filesystem   npx -y @modelcontextprotocol/server-filesystem .   connected
github       npx -y @modelcontextprotocol/server-github         connected
sentry       https://mcp.sentry.dev/sse                          connected
notion       oauth (google-managed)                              needs auth

A real-world pattern I use: a local filesystem server plus a remote Sentry server together, so I can ask Gemini CLI to correlate a stack trace against local source:

> Use the sentry MCP tool to pull the top unresolved issue for the "checkout-service" project,
> then find the corresponding function in this repo using the filesystem tool and suggest a fix.

The trade-off calculus for local vs. remote is unchanged from the other three tools: local stdio servers give you full control and no network dependency but require every teammate to have the runtime (npx, uvx, etc.) installed; remote servers centralize maintenance but add a network hop and an external dependency to your agent's reliability.

Tips
- Use gemini mcp auth <name> for anything OAuth-based rather than trying to hand-roll a bearer token flow in JSON — Gemini CLI's keychain storage is meaningfully safer than a token sitting in settings.json.
- When mixing local and remote servers in one workflow, put the remote (network-dependent) server second in your prompt's tool sequence when order matters — a timeout on the remote call shouldn't block work that only needs the local tool.

Comparing Gemini CLI and Claude Code MCP Configuration Side by Side

Given how many teams run both tools (developers picking whichever CLI suits the task, or comparing outputs), here's the direct comparison I keep pinned for reference:

If you're standardizing a team that uses both tools, the practical move is to keep a single canonical list of MCP servers (name, command, required env vars) in a shared doc, then translate that list into each tool's specific JSON shape — the command/args stdio definitions are nearly copy-paste compatible, but always double-check the remote-server key names before assuming a config "ported" cleanly.

Tips
- Don't assume a config file copy-pasted between Claude Code and Gemini CLI works unchanged — the stdio half usually does, the remote-server half almost never does because of the type vs. httpUrl/url difference.
- If you support both tools across a team, maintain one internal reference table (like the one above, customized to your actual MCP servers) rather than relying on tribal knowledge — this is exactly the kind of thing that causes a 30-minute Slack thread every time someone onboards.

Tips

Tips
- Use .gemini/.env for local secrets instead of shell exports — it's a genuine ergonomic win over Claude Code's config, but keep it gitignored and ship a .env.example for the team.
- Reserve trust: true for vetted, read-only servers only; it removes a safety check, not just a UI annoyance.
- When debugging a "works in Claude Code, fails in Gemini CLI" MCP config, check the remote-transport key names first — it's the single most common porting mistake between the two tools.