Add an MCP server to Gemini CLI: mcpServers in settings.json
Connecting MCP servers to Gemini CLI: the mcpServers block in settings.json, user versus project scope, passing tokens through the environment, and the trust key.
Contents
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.
KEY POINT
What you will learn
mcpServersinsettings.json, and when to use user versus project scope- Checking connections with
/mcp, and thetrustkey for tool approval - A checking order for when a server doesn't work
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 |
Never put a token directly in settings.json
A project's .gemini/settings.json gets committed. Write an environment variable reference in env and keep the value in your shell. For a server that uses a personal token, another option is to define it in your own ~/.gemini/settings.json instead of the project file.
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.
用語解説
includeTools / excludeTools: per-server settings that narrow which tools the model may use. Use them for something like allowing issue reads from a GitHub server while excluding creation and deletion.
When a server doesn't work
- Start the server on its own: run
npx @playwright/mcp@latestin a terminal and look for errors. - Environment variables:
echo $GITHUB_TOKEN. If the shell that launched Gemini CLI lacks it, the server won't get it. - JSON syntax: a trailing comma or unclosed quote is the usual cause. Configuration errors are reported when
geministarts. - Timeout: the first
npxrun spends time downloading the package. Raisetimeout, or run it once by hand first. - 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
mcpServersin~/.gemini/settings.json(user) or.gemini/settings.json(project) command,argsandenvmatch Claude Code's.mcp.json; read tokens from environment variables/mcpshows connection state,/toolslists every available tool- Reserve
trustfor read-only servers and keep confirmation on anything that writes
FAQ
- Where does Gemini CLI MCP configuration go?
- In mcpServers in ~/.gemini/settings.json for every project, or in .gemini/settings.json inside a repository for one project.
- Does a Claude Code .mcp.json work here?
- The command, args and env values are the same, and so is the top-level mcpServers key, so the contents port over almost unchanged.
- How do I check a server is connected?
- Run /mcp in a session. It shows each server's connection state and the tools it provides. /tools lists built-in and MCP tools together.
Questions & answers
Q. Since Gemini CLI 0.63.0 an "Untrusted Command Flags" warning interrupts even in YOLO mode, on basic file operations through MCP servers. Is there a setting to cut the confirmations down?
The "Untrusted Command Flags" warning itself could not be found in the official configuration or command references as of 2026-10-12, and there is no documented key that turns that particular check off. What follows is therefore the set of documented levers for reducing MCP tool confirmations.
1. Trust the server (settings file)
mcpServers.<SERVER_NAME>.trust is documented as a boolean that "trusts the server and bypasses tool call confirmations." It skips the confirmation for that server's tool calls.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
"trust": true
}
}
}
Put it in ~/.gemini/settings.json for your user or .gemini/settings.json for the project.
2. Name the tools instead (launch flag)
--allowed-tools is documented as "A comma-separated list of tool names that will bypass the confirmation dialog." That narrows the bypass to specific tools rather than a whole server.
3. Re-check the approval mode
general.defaultApprovalMode takes default, auto_edit or plan. YOLO mode cannot be enabled from a settings file at all — only from the command line with --yolo or --approval-mode=yolo — and --approval-mode cannot be used together with --yolo. Note also security.disableYoloMode: when it is true, YOLO stays off even if a flag enables it (it requires a restart). If your machine is managed, it is worth checking that this is not switched on without your knowing.
注意
trust: true waives the confirmation for every tool call that server makes. On a filesystem server, or any server that can run arbitrary commands, that widens what runs unattended to everything that server can do. Reserve it for servers whose arguments and reachable paths you have pinned down yourself.
More detail: Add an MCP server to Gemini CLI.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.