Connect an MCP server to Gemini CLI

Gemini CLI reads MCP servers from the mcpServers block of its settings.json — user-wide or per-project — with a gemini mcp command that writes it for you. Remote servers take a URL, local servers a launch command; every brand page here tells you which kind you're dealing with.

Where the config lives

Local (stdio) servers

One command, or the JSON it generates:

gemini mcp add example npx -y @vendor/mcp-server

# user scope instead of the current project
gemini mcp add -s user -e VENDOR_API_KEY=sk-… example npx -y @vendor/mcp-server

gemini mcp list
gemini mcp remove example

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@vendor/mcp-server"],
      "env": { "VENDOR_API_KEY": "$VENDOR_API_KEY" }
    }
  }
}

Python servers use uvx as the command. $VAR references in env values resolve from your environment at launch, keeping the secret out of the file.

Remote (hosted) servers

Current remote servers speak streamable HTTP, which Gemini CLI configures with httpUrl — plain url means legacy SSE:

{
  "mcpServers": {
    "linear": {
      "httpUrl": "https://mcp.linear.app/mcp"
    }
  }
}

For OAuth servers, the CLI discovers the endpoints, opens your browser to sign in, and stores tokens in ~/.gemini/mcp-oauth-tokens.json. Token-based servers take a headers object instead. Inside a session, /mcp shows every server's connection status and tools, and /mcp auth <name> re-runs a sign-in. Servers you can add this way right now: fal.ai, Atlassian, Datadog, Buffer, Google Drive, Confluence.

Worth knowing

When it doesn't work

A word on trust

An MCP server runs with the credentials you give it, and Gemini acts on whatever it returns. Prefer official servers where they exist, give community ones scoped, revocable keys, and be deliberate about trust: true. More in our MCP security guide.

Questions