Gemini CLI MCP: Setup + Best Servers (2026)

By default, Gemini CLI can read your files and run shell commands, and that’s where its reach ends. It can’t open a pull request, query your production database, or pull a component out of a Figma file. The Model Context Protocol closes that gap: wire up an MCP server, and the Gemini CLI gains tools it can call directly, turning it from a chat-in-your-terminal tool into something that can actually interact with the systems you work in.

One thing to settle first. As of June 18, 2026, Google stopped serving Gemini CLI requests on the free, AI Pro, and Ultra tiers; individuals moved to the closed-source Antigravity CLI (the agy command). The open-source repo is still under Apache-2.0, but now requires either a paid Gemini API key or an enterprise Gemini Code Assist license, which is what everything below assumes. The MCP model is nearly identical across both, so this still applies if you’ve migrated.

What is an MCP server in Gemini CLI?

An MCP server is a small program that exposes tools, resources, and prompts to an MCP client over a standard protocol. Gemini CLI is the client; the server bridges the Gemini model to an external system: a GitHub repo, a Postgres instance, a browser, your internal API.

MCP itself is an open standard Anthropic published in November 2024; clients and servers talk over JSON-RPC, so you stop writing one-off integrations for every tracker, database, or repo.

Inside Gemini CLI, it connects to each configured server on startup, asks which tools it offers, and registers them. When the model needs a tool, the CLI routes the call to the right server and returns the result, exactly like a built-in tool, so you don’t need to prompt differently to use one.

How to set up an MCP server (settings.json)

MCP servers live in settings.json: a global config at ~/.gemini/settings.json applies everywhere, and a project config at .gemini/settings.json applies only inside that repo. Project config is the better default for anything team-specific, since it travels with the codebase.

Servers go in a top-level mcpServers object, keyed by a name you choose. Here is a local server launched as a subprocess:

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

A few fields matter most. env expands $VAR_NAME or ${VAR_NAME}, keeping secrets out of the file you commit. timeout is in milliseconds, defaulting to 600,000 (ten minutes). trust defaults to false and gates whether the CLI confirms each tool call; set it to true only for servers you fully control, since it skips every confirmation.

If you’d rather not hand-edit JSON, Gemini CLI ships a gemini mcp command group that writes the same config for you:

# Local stdio server (default transport)
gemini mcp add python-server python server.py -- --port 8080

# Remote HTTP server with an auth header
gemini mcp add --transport http secure-http https://api.example.com/mcp/ \
  --header "Authorization: Bearer abc123"

# See what's configured and connected
gemini mcp list

By default, gemini mcp add writes to the project scope; pass -s user for the global config instead. gemini mcp remove deletes an entry.

Popular MCP servers and extensions (GitHub, Figma, databases)

The servers worth installing first are the ones that map to where your work already lives.

GitHub’s first-party MCP server is the one most teams reach for first, since an agent that can read a repo but not open a PR is only half useful. A design-to-code workflow relies on a Figma server for frames and variables; a database server lets the model inspect the schema before writing a migration, rather than guessing. Auth-focused servers, like Auth0’s, are well-suited to teams managing identity from the terminal.

One caveat applies everywhere: tool descriptions and returned data are injection surfaces, since a poisoned issue body or a malicious page can carry instructions back to the model. Scope tokens tightly, prefer read-only modes, and use the per-tool includeTools and excludeTools filters to keep an agent’s reach narrow.

Remote vs local (SSE/HTTP) limitations

Gemini CLI supports three transports, and the one you pick is decided by which field you set in the server config:

• command runs a local subprocess over stdio. Simplest, lowest latency, no network.
• httpUrl connects to a Streamable HTTP endpoint, the current standard for remote servers.
• url connects to a Server-Sent Events endpoint. SSE is now a streaming mode inside Streamable HTTP; these endpoints stick around mostly for back-compat.

Remote servers add real capability, but also the hardest part of the setup: auth. Gemini CLI handles OAuth 2.0 for SSE and HTTP servers and can discover the endpoints automatically on a 401, but the flow needs a browser: it opens a sign-in page and listens for the redirect on a localhost callback URL, on an OS-assigned random port by default. That breaks remote MCP in headless environments, such as CI, remote SSH without X11 forwarding, or browserless containers. A local stdio server, or running the agent somewhere it can complete the handshake once, is the simplest fix.

FastMCP: building your own server

When no off-the-shelf server fits, you write one. FastMCP is the most common way to do that in Python: decorate a function, and the framework generates the schema, validation, and protocol plumbing around it. FastMCP 1.0 was folded into the official MCP Python SDK, so the basic decorators are available there too.

Build the server, then test it in isolation: run it against the MCP inspector, call each tool by hand, and confirm the inputs and outputs look right before you add it to settings.json. Once registered, it behaves like any other server; its tools join the registry, and you can even expose prompts as slash commands.

Connecting context across many agents and repos at scale

Everything above wires one agent to one set of tools on one machine. That works on a laptop. It frays the moment a team tries to run it.

The failure mode is config drift. Fifty engineers each keep their own settings.json, with different server versions, scopes, and tokens that nobody reviews. The same server gets a read-only token on one laptop and a write-everything token on another, and scheduled agents can’t complete the interactive OAuth flow at all. The question shifts from “how do I connect a server?” to “how do I give many agents governed, consistent access to the same context?”

This is the layer we work at. Instead of every developer maintaining MCP config locally, the protocol lives at the workspace level: GitHub, Linear, Sentry, and Postgres light up automatically once connected, and the rest of the stack (GitLab, Jira, Slack, Notion, and others) connects with a UI click, alongside your own custom stdio, HTTP, or SSE servers. Because we’re agent-agnostic, that same connected context is available whether the task runs on Claude Code, Codex, Cursor, or Opencode, and each agent runs in an isolated sandbox so a compromised tool can’t reach your machine.

That shared context is what makes the orchestration useful: an agent triggered by a Slack mention or a new Linear issue can read your Sentry errors and codebase in a single run, and a single task can fan out into coordinated PRs across several repos, per our guide to multi-agent orchestration. See our best MCP servers roundup for which servers earn a slot.

Troubleshooting (MCP disconnected, config issues)

Run /mcp first. It lists every configured server, its status (CONNECTED, CONNECTING, or DISCONNECTED), the tools each one exposes, and the overall discovery state. Most problems sort into three buckets:

Run with –debug when the status display isn’t enough. A server that works standalone but breaks when sandboxed usually lacks a missing dependency or a network path; packaging it in Docker is the reliable fix. Start with one server, confirm it connects, then add complexity.

Conclusion

MCP turns Gemini CLI from a terminal assistant into something that can act on your repos, your designs, and your data. The setup is a settings.json entry and a transport choice; the limits are mostly about remote auth and the browser it needs; the rest is picking servers that match your work and scoping their tokens carefully.

The harder problem shows up later, when one agent becomes a team of them, and the local MCP config turns into drift that no one is auditing. If that’s where you’re headed, try our free tier (10 free credits, a one-time grant rather than a recurring refresh, on one repository, with the option to top up anytime) and connect a server through the UI to see what governed, multi-agent MCP looks like in practice.

FAQ

What is MCP in Gemini CLI? An open standard that lets Gemini CLI call external tools through a server. You define servers in settings.json, the CLI discovers their tools on startup, and the model can use them like its built-in ones.

Where is the Gemini CLI MCP config file? In settings.json: ~/.gemini/settings.json for global config, or .gemini/settings.json inside a project for repo-specific servers. Add servers under the mcpServers object, or use gemini mcp add to write the entry for you.

How do I list MCP servers in Gemini CLI? Run /mcp inside the CLI to see every server, its connection status, and its tools, or gemini mcp list from your shell.

Does Gemini CLI support remote MCP servers? Yes, over Streamable HTTP (httpUrl) and legacy SSE (url). Remote servers can use OAuth 2.0, but the flow needs a local browser and a localhost redirect, so it won’t complete in headless or container environments without extra setup.

Is Gemini CLI still free after June 2026? No. As of June 18, 2026, the free, AI Pro, and Ultra tiers moved to Antigravity CLI. The open-source CLI still runs with a paid Gemini API key or an enterprise Gemini Code Assist license, and MCP works the same way on both.