Add MCP servers to Gemini CLI

Gemini CLI reads mcpServers from settings.json in ~/.gemini/ or in the project's .gemini/ folder.

macOS

~/.gemini/settings.json

Windows

~/.gemini/settings.json

Linux

~/.gemini/settings.json

Project file

.gemini/settings.json

Top-level key

mcpServers

Format

json

OAuth for remote servers

●Yes

Example config

This example adds GitHub's hosted server and Playwright as a local server, in the shape this client expects.

{
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/"
    },
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

gemini mcp add -s project -t http github https://api.githubcopilot.com/mcp/
gemini mcp add -s project playwright npx @playwright/mcp@latest

Notes and quirks

• The field name picks the transport: httpUrl for Streamable HTTP, url for SSE, command for stdio.
• gemini mcp add writes to project scope unless you pass -s user.
• includeTools and excludeTools filter which tools the model sees.
• OAuth tokens are saved in ~/.gemini/mcp-oauth-tokens.json.

Build a Gemini CLI config →

Other clients