Skip to main content

How to Connect MCP Servers to Gemini CLI

Short answer

Gemini CLI reads MCP servers from an mcpServers object in ~/.gemini/settings.json, or in .gemini/settings.json inside a project. A local server needs a command and args; a remote server needs an httpUrl. Add the entry with gemini mcp add -s user, restart Gemini CLI, then run /mcp to check it connected.

Gemini CLI has stopped serving individual accounts

On June 18, 2026, Gemini CLI stopped serving requests for Google AI Pro and Ultra accounts, and for the free Gemini Code Assist for individuals tier. It still works with Gemini API keys and with Gemini Code Assist Standard or Enterprise licenses. For individual accounts, Google's replacement is Antigravity CLI, which migrates your Gemini CLI MCP servers. The steps below are for Gemini CLI.

Tested withGemini CLI 0.4.1 (gemini mcp add, list and remove, run on macOS)Gemini CLI docs, main branch, read 2026-10-20MCP Python SDK server from the build guide, uv runChecked 20 Oct 2026

By Tony LewisHow we test these guides

What you'll have at the end​

A server listed as connected in Gemini CLI's own status output. This is the output of gemini mcp list for the stdio server in step 2:

Configured MCP servers:

bookmarks: uv --directory /tmp/acme-bookmarks run bookmarks.py (stdio) - Connected

Gemini CLI can then call the server's tools from a chat, named mcp_bookmarks_<tool name>.

Before you start

  • Gemini CLI installed (npm install -g @google/gemini-cli) and signed in with a method that still works (see the warning above).
  • For the local example, uv and a local MCP server. The example uses the bookmarks server from How to Build an MCP Server.
  • For the remote example, the URL of a Streamable HTTP MCP server. The examples use https://mcp.example.com/mcp as a placeholder.
  • A terminal, and a text editor for the JSON file.

1. Find the settings file​

Gemini CLI keeps MCP servers in its settings.json file. There are two places you can put them:

ScopemacOS and LinuxWindowsApplies to
User~/.gemini/settings.json%USERPROFILE%\.gemini\settings.jsonEvery project you open in Gemini CLI
Project.gemini/settings.json in the project folderSameOnly that project

~ means your home folder. A project file overrides user settings, so use the user file for servers you want everywhere. Create the file if it doesn't exist.

2. Add a local (stdio) server​

A local server runs on your computer. Gemini CLI starts it with the command and args you give, then talks to it over standard input and output. The bookmarks server from the build guide runs like this:

settings.json
{
  "mcpServers": {
    "bookmarks": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/bookmarks",
        "run",
        "bookmarks.py"
      ],
      "env": {
        "BOOKMARKS_FILE": "/ABSOLUTE/PATH/TO/bookmarks-data.json"
      },
      "timeout": 30000
    }
  }
}

Replace /ABSOLUTE/PATH/TO/bookmarks with the folder that holds bookmarks.py, and bookmarks-data.json with any file path you want the server to save to. The env block sets environment variables for that server's process. Other servers don't receive them.

You can also write the same entry from the terminal. The -s user flag matters: gemini mcp add writes to the project file unless you pass it.

gemini mcp add -s user bookmarks uv --directory /ABSOLUTE/PATH/TO/bookmarks run bookmarks.py

In Gemini CLI 0.4.1, the -e flag for environment variables took the server name and command as its values, so add an env block by editing the file as shown above.

Server names should use hyphens rather than underscores. Gemini CLI builds tool names as mcp_<server>_<tool> and reads the server name up to the first underscore after mcp_, so my_server can break its policy checks. Use my-server.

3. Add a remote server​

A remote server runs somewhere else and Gemini CLI connects to its URL. For a server that uses Streamable HTTP, set httpUrl:

settings.json
{
  "mcpServers": {
    "my-remote": {
      "httpUrl": "https://mcp.example.com/mcp",
      "timeout": 30000
    }
  }
}

Gemini CLI also accepts url for servers that use Server-Sent Events (SSE). If you set both httpUrl and url, httpUrl wins. Use httpUrl unless the server's documentation says it only supports SSE.

The command form writes the same entry:

gemini mcp add -s user --transport http my-remote https://mcp.example.com/mcp

Use headers to send a fixed header, such as an API key, with each request. Keep secrets out of files you commit to a project. The user file is the safer place for them.

4. Sign in with OAuth​

If a remote server needs sign-in, Gemini CLI handles it when you connect. The first connection gets a 401 Unauthorized response, Gemini CLI finds the server's sign-in details, opens your browser, and stores the tokens it receives in ~/.gemini/mcp-oauth-tokens.json. Gemini CLI refreshes expired tokens when the server issued a refresh token.

From inside a Gemini CLI session:

/mcp auth
/mcp auth my-remote

The first command lists servers that need sign-in. The second signs in to one server. Run it again to sign in again after tokens expire.

OAuth needs a browser on the same machine as Gemini CLI, because the sign-in redirect comes back to a local port. It doesn't work in headless environments, in remote SSH sessions without X11 forwarding, or in containers without browser support. The oauth block in settings.json lets you set the client ID, scopes and endpoints yourself. The Gemini CLI MCP reference lists every option.

5. Check it worked​

Restart Gemini CLI. It starts the servers listed in your settings when it opens. Then check their status in a session:

/mcp

From a regular terminal, gemini mcp list shows every configured server and whether it connected. Gemini CLI only shows local (stdio) servers as connected when the folder you run it from is trusted, so if a local server shows as disconnected, read the first problem below.

Once a server is connected, ask Gemini CLI to use one of its tools by describing the task. The tools appear with names like mcp_bookmarks_save_bookmark.

Common problems​

Disconnected next to a stdio server. Gemini CLI only reports local servers as connected in folders it trusts. The Gemini CLI docs say to run gemini trust from inside the folder, then run gemini mcp list again to confirm the status changed.

MCP issues detected. Run /mcp list for status. A server failed when Gemini CLI started. This hint only appears at startup. Run /mcp in the session for the details on each server.

A server connects, but its tools are missing. Check the server's includeTools and excludeTools lists. If includeTools is set, only the tools named in it are available. excludeTools wins when a tool appears in both.

The request times out. Requests time out after 600,000 milliseconds (10 minutes) by default. Set timeout in the server's entry to change that, in milliseconds, as the examples do.

For more errors and fixes across AI apps, see Fix MCP connection errors.

FAQ​

Is Gemini CLI still available?

It still works with Gemini API keys and with Gemini Code Assist Standard or Enterprise licenses. Google stopped serving Google AI Pro and Ultra accounts on June 18, 2026, and points those users to Antigravity CLI, which migrates your Gemini CLI MCP servers.

Where does Gemini CLI store its MCP servers?

In the mcpServers object of settings.json. The user file is ~/.gemini/settings.json and applies everywhere. A project file at .gemini/settings.json in the project folder applies only to that project and overrides the user file.

What is the difference between url and httpUrl?

httpUrl is for servers that use Streamable HTTP. url is for servers that use Server-Sent Events. If both are set, Gemini CLI uses httpUrl. New remote servers should use httpUrl.

Why does gemini mcp add write to the project file?

Its default scope is project. Pass -s user to write to ~/.gemini/settings.json so the server is available in every project.

Can I use the same server in Claude Code or Cursor?

Yes. Each app keeps its own MCP configuration file, and the server itself doesn't change. The Claude Code and Cursor guides show where each one keeps its file.