Add an MCP server to Gemini CLI: mcpServers in settings.json

Gemini CLI supports MCP (Model Context Protocol), so you can connect browser control, documentation lookup and other external tools. The configuration is JSON under mcpServers in settings.json, which is close to identical to Claude Code's .mcp.json.

This article covers where the file lives, how to write the block, how to check the connection, how tool approval works, and what to check when a server doesn't start.

Where the configuration lives

Scope	Path	Use for
User	~/.gemini/settings.json	Servers you want in every project
Project	<repo>/.gemini/settings.json	Servers shared with your team, in version control

When both files define servers, the two are merged, and a server defined in both takes the project version.

Writing the mcpServers block

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 30000
    }
  }
}

Key	Meaning
command	The command that starts the server
args	Arguments, as an array
env	Environment variables for the server; $VAR and ${VAR} reference your shell's
cwd	Working directory at startup (optional)
timeout	Milliseconds to wait for a response (optional)
url / httpUrl	The URL of a remote server, in place of a stdio command

Checking the connection

Start Gemini CLI and run /mcp. You get each server's state — connected, connecting or disconnected — plus the names of the tools it provides. /tools lists the built-in tools and the MCP tools together.

On first launch you may be asked whether Gemini may use the tools a server provides.

Approving tool calls

MCP tool calls are confirmed before they run. For a tool you don't want to confirm every time, choose the always-allow option in the dialog, or mark the server as trusted in settings.json.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "trust": true
    }
  }
}

With trust set to true, that server's tools run without confirmation. Keep it to read-only servers such as documentation lookup, and never set it on a server that writes or sends data outward. Which configuration keys your version supports changes over time, so check the official configuration reference.

When a server doesn't work

1. Start the server on its own: run npx @playwright/mcp@latest in a terminal and look for errors.
2. Environment variables: echo $GITHUB_TOKEN. If the shell that launched Gemini CLI lacks it, the server won't get it.
3. JSON syntax: a trailing comma or unclosed quote is the usual cause. Configuration errors are reported when gemini starts.
4. Timeout: the first npx run spends time downloading the package. Raise timeout, or run it once by hand first.
5. Node.js version: confirm it meets what the server requires.

How this compares across the three tools

Tool	Config file	Format
Gemini CLI	~/.gemini/settings.json / .gemini/settings.json	JSON, mcpServers
Claude Code	.mcp.json / ~/.claude.json	JSON, mcpServers
Codex	~/.codex/config.toml	TOML, [mcp_servers.<name>]

Claude Code uses the same key names, so pasting the contents of a .mcp.json into .gemini/settings.json often just works. For Claude Code see Adding MCP servers to Claude Code, and for Codex Add an MCP server to Codex CLI. For which servers to start with, see Five MCP servers worth installing first.

Summary

• Write mcpServers in ~/.gemini/settings.json (user) or .gemini/settings.json (project)
• command, args and env match Claude Code's .mcp.json; read tokens from environment variables
• /mcp shows connection state, /tools lists every available tool
• Reserve trust for read-only servers and keep confirmation on anything that writes