# Gemini CLI MCP: how to connect MCP servers to Google's 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 on mcpyet.com tells you which kind you're dealing with — 212 of 234 brands have official servers ([full index](https://mcpyet.com/browse.md)).

## Where the config lives

| Path | Scope | Good for |
| --- | --- | --- |
| `~/.gemini/settings.json` | Every project | Personal servers — docs search, utilities |
| `.gemini/settings.json` | This project | Repo-specific tools; commit it to share with the team |

## Local (stdio) servers

One command, or the JSON it generates:

```sh
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
```

```json
{
  "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:

```json
{
  "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](https://mcpyet.com/mcp/fal-ai.md), [Atlassian](https://mcpyet.com/mcp/atlassian.md), [Datadog](https://mcpyet.com/mcp/datadog.md), [Buffer](https://mcpyet.com/mcp/buffer.md), [Google Drive](https://mcpyet.com/mcp/google-drive.md), [Confluence](https://mcpyet.com/mcp/confluence.md).

## Worth knowing

| Setting | Does |
| --- | --- |
| `trust: true` | Skips tool-call confirmations for that server — leave off for anything that writes |
| `includeTools` / `excludeTools` | Per-server tool allowlist / blocklist (exclude wins) |
| `timeout` | Per-request timeout in ms (default 600,000) |
| `headers` | Custom HTTP headers for remote servers |
| `cwd` | Working directory for stdio servers |

## When it doesn't work

| Symptom | Usual cause | Fix |
| --- | --- | --- |
| Server never appears | Invalid JSON, or wrong file | Run `/mcp` to see what loaded; check which scope you edited |
| Appears, fails to start | `npx` not on PATH | Use the absolute path from `which npx` |
| Starts, then exits | Missing API key | Set it in `env` — run the command in a terminal for the real error |
| Remote server won't connect | SSE field for an HTTP server | Use `httpUrl` for streamable HTTP; `url` is SSE only |
| 401 after weeks of working | Expired OAuth grant | `/mcp auth <name>` to re-authenticate |

## 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 (<https://mcpyet.com/browse/official/>), give community ones scoped, revocable keys, and be deliberate about `trust: true`. More in the [MCP security guide](https://mcpyet.com/guides/mcp-security.md).

## Questions

**Where does Gemini CLI keep its MCP config?**
In the mcpServers block of settings.json — ~/.gemini/settings.json for servers you want everywhere, .gemini/settings.json in a project for repo-specific ones. gemini mcp add writes to the same files via its --scope flag.

**What's the difference between url and httpUrl?**
Transport. url declares a legacy SSE server; httpUrl declares a streamable HTTP server, which is what current remote servers ship. If a remote server won't connect via url, switching the field to httpUrl is the usual fix.

**How does OAuth work in a terminal?**
Gemini CLI discovers the server's OAuth endpoints, registers itself dynamically, and opens your browser for the sign-in. Tokens are stored in ~/.gemini/mcp-oauth-tokens.json and refreshed automatically; /mcp auth <server> re-runs the flow when a grant expires.

**What does the trust setting do?**
trust: true skips the confirmation dialog on every tool call from that server. Convenient, and exactly the thing to leave off for servers that can write or that fetch untrusted content.

**Can I use only some of a server's tools?**
Yes — includeTools is an allowlist and excludeTools a blocklist per server (excludeTools wins on conflict). Useful both to save context and to strip write-capable tools from a server you only read from.

Related guides: [Codex CLI](https://mcpyet.com/connect/codex.md) · [Claude](https://mcpyet.com/connect/claude.md) · [Remote MCP servers](https://mcpyet.com/guides/remote-mcp-servers.md)

---

Source: https://mcpyet.com/connect/gemini-cli/ — data refreshed 2026-08-11