Skip to content
AgentAtlas

Gemini CLI MCP servers: gemini mcp add and mcpServers in settings.json

How do I add an MCP server to Gemini CLI?

Run gemini mcp add with a name and a command or URL, or add an entry under mcpServers in settings.json. Each server needs one of command (stdio), url (SSE) or httpUrl (streamable HTTP). Check status with gemini mcp list in your shell or /mcp inside the CLI.

Compare: add an MCP server in every AI coding agent →

Add a server from the command line

gemini mcp add writes to .gemini/settings.json by default. Use -s user to write to ~/.gemini/settings.json instead.

stdio server

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

HTTP server with a header

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

SSE server

gemini mcp add --transport sse sse-server https://api.example.com/sse/
  • -s, --scope: user or project. Default is project.
  • -t, --transport: stdio, sse or http. Default is stdio.
  • -e, --env and -H, --header: set env vars and HTTP headers.
  • --trust: skip all tool call confirmations for this server.
  • --include-tools and --exclude-tools: comma separated tool lists.
  • --timeout: connection timeout in milliseconds.

Configure mcpServers in settings.json

settings.json

{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}
  • Required: one of command, url or httpUrl.
  • timeout is in milliseconds. Default is 600,000 (10 minutes).
  • trust defaults to false. true bypasses all confirmations for that server.
  • includeTools is an allowlist. excludeTools wins if a tool is in both.
  • headers sets custom HTTP headers for url or httpUrl servers.

Keep secrets out of the file

Values in env can reference variables with $VAR or ${VAR} on all platforms, or %VAR% on Windows. The CLI redacts sensitive host variables such as *TOKEN*, *SECRET* and *KEY* from MCP processes unless you list them explicitly in env.

Allow or block servers globally

settings.json

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

List, remove, disable and authenticate

Shell

gemini mcp list
gemini mcp remove my-server
gemini mcp disable my-server --session
gemini mcp enable my-server

Inside Gemini CLI

/mcp
/mcp auth
/mcp auth serverName

stdio servers only show as Connected in gemini mcp list when the current folder is trusted. Remote servers that need OAuth open a browser for sign in, so this does not work in headless or SSH sessions without a browser.

Sources

More Gemini CLI guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →