Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 1 · Lesson 2 · 4 min read

How to Add MCP Servers to Gemini CLI

On this page
  1. The problem you'll probably hit first
  2. Step 1: add a server with `gemini mcp add`
  3. Step 2: check what was written
  4. Step 3: trust the folder
  5. Step 4: confirm the server connected
  6. Common errors and fixes
  7. Check yourself

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):

Code
# 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:

  • -s or --scope is user or project. The default is project, which writes to .gemini/settings.json in the current folder and fails if the folder isn't trusted. Pass -s user for servers you want everywhere.
  • -t or --transport is stdio (the default), http or sse. Remote servers need -t http.
  • -e KEY=value sets 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:

JSON
{
  "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:

Code
/permissions trust

Trust 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

Code
gemini mcp list

You should see a line per server with its status:

Code
✓ playwright: npx -y @playwright/mcp@0.0.84 (stdio) - Connected

Inside 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 seeCauseFix
"Cannot modify settings in an untrusted workspace"Default project scope in an untrusted folderAdd -s user, or trust the folder first
Server shows Disabled in gemini mcp listThe current folder isn't trusted/permissions trust, or open a trusted folder
Disconnected for a remote server, or 401 errorsThe variable in the header isn't set, so the literal text $GITHUB_PAT is sent as the tokenExport the variable in the shell you start Gemini CLI from, then restart it
Times out on first runnpx is downloading the packageRun 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.