Search

Home › Learn › Add an MCP server to Gemini CLI

Add an MCP server to Gemini CLI

Updated 2026-11-01

Gemini CLI reads MCP servers from an mcpServers object in settings.json, and offers a gemini mcp command to edit it for you. The details below come from the Gemini CLI repository's MCP documentation as read on 2026-11-01.

Add a server with the CLI

gemini mcp add [options] <name> <commandOrUrl> [args...]

The transport defaults to stdio, so a local server only needs its command:

gemini mcp add -e API_KEY=123 my-stdio-server /path/to/server arg1 arg2

# Arguments meant for the server go after --
gemini mcp add python-server python server.py -- --server-arg my-value

Remote servers need --transport:

# Streamable HTTP
gemini mcp add --transport http http-server https://api.example.com/mcp/

# With an auth header
gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/

# SSE
gemini mcp add --transport sse sse-server https://api.example.com/sse/

Other flags are --timeout, --trust, --description, --include-tools and --exclude-tools.

Mind the default scope

--scope defaults to project, which writes to .gemini/settings.json in the current folder. Use -s user to write to ~/.gemini/settings.json so the server is available everywhere. gemini mcp remove also defaults to project scope, so pass the same -s value when removing a user-scope server.

Edit settings.json directly

{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Each server needs exactly one of three connection fields, and the difference between the last two catches people out:

FieldTransport
commandstdio
urlSSE
httpUrlStreamable HTTP

So a Streamable HTTP endpoint belongs in httpUrl, even though other clients use url for it:

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "https://api.example.com/mcp",
      "headers": { "X-Custom-Header": "custom-value" },
      "timeout": 5000
    }
  }
}

Optional fields include args, headers, env, cwd, timeout (milliseconds, default 600,000), trust, includeTools and excludeTools.

Environment variables

The docs describe expansion in the env block using $VAR or ${VAR} on all platforms and %VAR% on Windows only. An undefined variable resolves to an empty string, so a typo shows up as a blank credential rather than an error. Referencing a variable keeps the token out of settings.json, which matters if a project-scope file is committed to a repository.

Limit what a server can do

See the security checklist for what to check before installing.

Check that it connected

From your shell:

gemini mcp list

Inside a session, /mcp shows each server's status and tools. If a stdio server shows as disconnected, check the folder first: the docs say stdio servers are only tested and shown as connected when the current folder is trusted, which gemini trust sets.

Connection errors are quiet by default at startup; you may only see a hint to run /mcp list. To test the server outside Gemini CLI, use the MCP Inspector.

OAuth

For remote servers using OAuth:

/mcp auth              # list servers requiring authentication
/mcp auth serverName   # authenticate, or re-authenticate if tokens expire

The docs' OAuth section also covers browser redirect requirements, which matter on headless machines.

Other commands

Where mcpnav fits

mcpnav's Connect block prints a generic mcpServers JSON snippet, generated from the Registry's packages and remotes. For stdio servers, command, args and env carry straight over. For remote servers, put the endpoint in httpUrl for Streamable HTTP or url for SSE.

What is not covered here

This article doesn't cover Google credentials, service account impersonation, MCP prompts as slash commands or extension-provided servers. All are in the source document below.

Sources

Sources