How to Add MCP Servers to Gemini CLI
On this page
The problem you'll probably hit first
You run gemini mcp add, it prints an error about an "untrusted workspace", and nothing is saved. Or the server is saved, but gemini mcp list shows it as Disabled. Both come from the same feature, folder trust, and both take ten seconds to fix once you know about it. This guide sets up a server the way that works the first time.
All commands below were run against Gemini CLI 0.67.0 in November 2026.
Step 1: add a server with `gemini mcp add`
The command takes a name, then either a command (for a local server) or a URL (for a remote one):
# Local server, for every folder you trust
gemini mcp add -s user playwright npx -y @playwright/mcp@0.0.84
# Remote server over HTTP, with a header
gemini mcp add -s user -t http github https://api.githubcopilot.com/mcp/ \
-H 'Authorization: Bearer $GITHUB_PAT'Three flags matter:
-sor--scopeisuserorproject. The default isproject, which writes to.gemini/settings.jsonin the current folder and fails if the folder isn't trusted. Pass-s userfor servers you want everywhere.-tor--transportisstdio(the default),httporsse. Remote servers need-t http.-e KEY=valuesets an environment variable for a local server, and-H "Name: value"sets an HTTP header for a remote one.
Note the single quotes around the header. They stop your shell from expanding $GITHUB_PAT now, so the file stores the variable name and Gemini CLI fills it in each time it starts.
Step 2: check what was written
User-scope servers go to ~/.gemini/settings.json. After the two commands above it looks like this:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@0.0.84"]
},
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"type": "http",
"headers": { "Authorization": "Bearer $GITHUB_PAT" }
}
}
}You can edit this file by hand instead of using the command. Gemini CLI expands $VAR, ${VAR} and ${VAR:-default} in these values, so tokens can stay in your environment.
Other useful flags on gemini mcp add: --timeout (milliseconds to wait for the server to connect), --include-tools and --exclude-tools (load only some of a server's tools), and --trust, which skips every tool confirmation for that server. Leave --trust off for anything that can write or delete.
Step 3: trust the folder
Gemini CLI won't run MCP servers in a folder you haven't trusted. In an untrusted folder, even your user-level servers are switched off, so that cloning a repository can't start programs on your machine without your say.
When you open Gemini CLI in a new folder, it asks whether to trust it. Choose to trust the folder. If you dismissed that prompt, run this inside Gemini CLI:
/permissions trustTrust decisions are saved in ~/.gemini/trustedFolders.json. Only trust folders whose code you'd be willing to run, because a trusted project's .gemini/settings.json can add servers too.
Step 4: confirm the server connected
gemini mcp listYou should see a line per server with its status:
✓ playwright: npx -y @playwright/mcp@0.0.84 (stdio) - ConnectedInside a session, type /mcp to see each server's tools. Then ask for something only that server can do, such as "Open example.com and read me the heading."
To pause a server without deleting it, use gemini mcp disable playwright, then gemini mcp enable playwright to bring it back. gemini mcp remove playwright deletes it.
Common errors and fixes
| What you see | Cause | Fix |
|---|---|---|
| "Cannot modify settings in an untrusted workspace" | Default project scope in an untrusted folder | Add -s user, or trust the folder first |
Server shows Disabled in gemini mcp list | The current folder isn't trusted | /permissions trust, or open a trusted folder |
| Disconnected for a remote server, or 401 errors | The variable in the header isn't set, so the literal text $GITHUB_PAT is sent as the token | Export the variable in the shell you start Gemini CLI from, then restart it |
| Times out on first run | npx is downloading the package | Run the command once in a terminal, or raise --timeout |
Check yourself
Add it at user scope with -s user, or trust the folder and run the command again so it lands in the project's .gemini/settings.json.
Single quotes stop your shell from replacing the variable, so the settings file stores $GITHUB_PAT and not the token itself. Gemini CLI expands it each time it starts.
When the server has tools that change things, such as writing to a database or merging pull requests. --trust removes the confirmation prompt for every one of those calls.