How to add an MCP server to Gemini CLI

Add MCP servers to Gemini CLI with gemini mcp add or the mcpServers block in settings.json, for one project or for every project.

Local servers: Yes; runs stdio servers
Hosted servers: Yes; connects by URL
Config: JSON; how servers are added
Picks: 7; ranked

Run gemini mcp add <name> <command> for a local server or gemini mcp add --transport http <name> <url> for a hosted one. Servers are saved to .gemini/settings.json in the project by default, or to ~/.gemini/settings.json with --scope user. Gemini CLI is now offered for Gemini Code Assist Standard and Enterprise licenses; free and Google AI Pro or Ultra accounts moved to Antigravity CLI in June 2026.

Good for

Teams with Gemini Code Assist Standard or Enterprise who want Gemini to reach GitHub, databases or docs
Projects that commit shared servers in .gemini/settings.json
People who need per-server tool allowlists and trust settings
Anyone whose remote server needs a browser sign-in

Install Gemini CLI

Gemini CLI

Copy this prompt.

Add the Gemini CLI MCP server to Gemini CLI. Run this command:

npm install -g @google/gemini-cli

Then check that it loaded and tell me if I need to sign in or restart.

2
Paste it into Gemini CLI. It shows the change and asks before running it.

Requires Node.js.

Then run gemini in a project folder. The README says Gemini CLI is designed for Gemini Code Assist Standard / Enterprise licenses and Code Assist for GitHub on Google Cloud, plus legacy paid API or Vertex keys. Free individual access and Google AI Pro / Ultra moved to Antigravity CLI on June 18, 2026. Add servers with gemini mcp add or by editing settings.json, as shown below.

From the vendor's docs. Source.

At a glance

Add a local server: gemini mcp add <name> <command> [args...]
Add a hosted server: gemini mcp add --transport http <name> <url>
Transports: stdio, SSE and streamable HTTP
User config: ~/.gemini/settings.json, key mcpServers
Project config: .gemini/settings.json in the project root (default scope for gemini mcp add)
System config: /etc/gemini-cli/settings.json (Linux), /Library/Application Support/GeminiCli/settings.json (macOS), C:\ProgramData\gemini-cli\settings.json (Windows)
OAuth: Yes, for SSE and HTTP servers; run /mcp auth <name>; needs a local browser
Resources and prompts: Both; resources via @server://path, prompts become slash commands
Check servers: gemini mcp list, or /mcp in the app
Default timeout: 600,000 ms (10 minutes) per request
Tool limit: Not stated in the docs; includeTools and excludeTools filter per server
Plan: Gemini Code Assist Standard or Enterprise, or paid API or Vertex keys

Add an MCP server to Gemini CLI

1
Add a local server with gemini mcp add
Put the launch command after the name. Pass keys with -e.
```
gemini mcp add github npx -y @modelcontextprotocol/server-github
gemini mcp add -e API_KEY=123 my-server /path/to/server
```
The default scope is the project. Add --scope user to use the server in every project.

Or add a hosted server by URL

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

Use --transport sse for a server that speaks Server-Sent Events.

Or edit settings.json by hand

Open ~/.gemini/settings.json (every project) or .gemini/settings.json (this project). Add an mcpServers object:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:latest"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}" }
    },
    "remote": { "httpUrl": "https://api.example.com/mcp" }
  }
}

command is stdio, httpUrl is streamable HTTP and url is SSE.

4
Limit tools if you want
Add includeTools (allowlist) or excludeTools to a server. excludeTools wins if a tool is in both. Add "trust": true only for servers you control, because it skips every confirmation.
5
Check it loaded
Restart Gemini CLI, then run gemini mcp list in your shell or /mcp inside the app. A working server shows Connected. Run /mcp reload after changing a server.
6
Sign in if it asks
For a hosted server that needs OAuth, run /mcp auth to list servers that need it, then /mcp auth <server-name>. Your browser opens to finish sign-in.
7
Switch a server off
Run gemini mcp disable <name>, or add --session to disable it for this session only. gemini mcp remove <name> deletes it.

Best MCP servers for Gemini CLI

Official servers with an approved PlugWiki page whose transport Gemini CLI supports (stdio or HTTP); ordered by GitHub stars, then weekly downloads.

MCP servers that work in Gemini CLI

40 · official first, then servers with a page, then by stars

Show all 40

Common errors and fixes

Local server shows Disconnected in gemini mcp list
Cause: The folder is not trusted, and stdio servers are only tested in trusted folders.
Fix: Run gemini trust in the folder, then run gemini mcp list again.
gemini-cli Source
Server shows DISCONNECTED in /mcp
Cause: The command, args or cwd are wrong, or the server needs a dependency.
Fix: Run the server command by hand to see its error, then fix command, args and cwd.
gemini-cli Source
Server connects but no tools appear
Cause: The server registers no tools, or its tool list is invalid.
Fix: Check the server logs, then run /mcp reload.
gemini-cli Source
OAuth sign-in never completes
Cause: Sign-in needs a local browser and a redirect to localhost; headless, SSH and container setups have neither.
Fix: Run /mcp auth on a machine with a browser, or use a header token with --header instead.
gemini-cli Source
OAuth fails with HTTP 400 Missing issuer parameter in response
Cause: You set issuer explicitly and the server does not return iss in its redirect.
Fix: Add "authorizationResponseIssParameterSupported": false to the oauth block.
gemini-cli Source
OAuth fails with HTTP 400 Issuer mismatch
Cause: The iss value in the redirect does not match the expected issuer.
Fix: Fix the issuer in the oauth block, or check the server points to the right authorization server.
gemini-cli Source
Server needs a secret but gets none
Cause: Gemini CLI strips variables like *TOKEN* and *KEY* from the inherited environment.
Fix: Set the variable in the server env block, for example "$MY_TOKEN".
gemini-cli Source
Policy rules for a server do nothing
Cause: The server name contains an underscore, so the policy parser misreads the name.
Fix: Rename the server with a hyphen, for example my-server.
gemini-cli Source

Verdict

Gemini CLI covers stdio, SSE and HTTP servers with browser OAuth, per-server tool filters and a gemini mcp command. The main limit is access: it is designed for Gemini Code Assist Standard / Enterprise, and free and Google AI Pro / Ultra access moved to Antigravity CLI on June 18, 2026.

Best for

Teams on Gemini Code Assist Standard or Enterprise
Projects that share servers through .gemini/settings.json

Skip it if

You are on a free or Google AI Pro or Ultra account
You need OAuth on a machine with no browser

Questions

How do I add an MCP server to Gemini CLI?

Run gemini mcp add <name> <command> for a local server, or gemini mcp add --transport http <name> <url> for a hosted one. Check it with gemini mcp list.

Where is the Gemini CLI MCP config file?

~/.gemini/settings.json for every project, under the mcpServers key. A project can also have .gemini/settings.json.

Does Gemini CLI support remote or HTTP MCP servers?

Yes. Use httpUrl for streamable HTTP and url for SSE, or gemini mcp add --transport http <name> <url>.

Does Gemini CLI support OAuth for MCP servers?

Yes, for SSE and HTTP servers. Run /mcp auth <server-name> and finish sign-in in your browser. It does not work on a machine with no browser, such as a headless server or a plain SSH session.

Project or global MCP servers in Gemini CLI?

gemini mcp add saves to the project by default. Add --scope user to save to ~/.gemini/settings.json so every project gets it.

How do I disable an MCP server in Gemini CLI?

Run gemini mcp disable <name>, or /mcp disable <name> in the app. Add --session to disable it only for this session.

Is there a limit on MCP tools in Gemini CLI?

The docs state no tool limit. You can trim a server with includeTools or excludeTools, and every tool gets a name like mcp_<server>_<tool>.

Does Gemini CLI MCP work on Windows and Linux?

Yes. The config file is in your home folder on every system, and env values accept $VAR everywhere and %VAR% on Windows.

Is Gemini CLI free to use with MCP servers?

Not for individuals any more. The README says free individual access and Google AI Pro / Ultra moved to Antigravity CLI on June 18, 2026. Gemini CLI is designed for Gemini Code Assist Standard / Enterprise licenses and Code Assist for GitHub, plus legacy paid API or Vertex keys.

Why does my stdio server show Disconnected in Gemini CLI?

In a folder you have not trusted, stdio servers show as Disconnected. Run gemini trust in that folder, then list the servers again.

Information

updated Nov 2, 2026

Transports: stdio, SSE, Streamable HTTP
Config file (all): ~/.gemini/settings.json
MCP docs: geminicli.com

Website Docs

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

Gemini CLI README · github.com
MCP servers with Gemini CLI · github.com
Gemini CLI cheatsheet · github.com
Gemini CLI configuration · github.com
Set up an MCP server · github.com