Skip to content

How to add an MCP server to Gemini CLI

Level 3: Connect AI to your tools. About 6 min. Checked on 19 November 2026.
Stage 3 of 4: Connect AI to your tools

In this lesson you'll add local and remote MCP servers to Gemini CLI, limit which tools it may use, and check that they connect.

Gemini CLI reads MCP servers from a settings.json file, and gives you a command to write it for you. One thing to check first: as of 19 November 2026, the Gemini CLI docs carry a notice that Gemini CLI was replaced by Antigravity CLI for unpaid-tier and Google One users on 18 June 2026. If that's you, see the Antigravity lesson instead.

Add a server with a command

# a local (stdio) server, with keys
gemini mcp add -e API_KEY=123 my-stdio-server /path/to/server arg1 arg2

# a remote server over Streamable HTTP
gemini mcp add --transport http http-server https://api.example.com/mcp/

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

The command writes to the project's .gemini/settings.json by default; use -s user for ~/.gemini/settings.json so the server works everywhere.

Or edit settings.json

Each server needs exactly one of command (local), url (SSE) or httpUrl (Streamable HTTP):

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer $MY_API_TOKEN"
      }
    }
  }
}

Values in env and headers can reference shell variables such as $MY_API_TOKEN, so keys stay out of the file.

Limit what it can do

  • includeTools lists the only tools the model may see; excludeTools hides tools (and wins over includeTools).
  • trust: true skips tool-call confirmations for that server. The docs advise it only for servers you fully control.
  • Avoid underscores in server names (my-server, not my_server): the docs warn that policy rules split tool names on underscores and can fail silently.

Check that it worked

Run gemini mcp list in a shell, or /mcp inside a session to see each server's status (CONNECTED, CONNECTING or DISCONNECTED) and its tools.

Servers developers use

MCP servers for developer tools from the directory, most popular first.

More for developer tools
  1. Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    • Remote
    • Open source
    • 34.6K GitHub stars
    • Developer tools
  2. Python framework for building MCP servers, clients and interactive apps

    Not checked yet
    • Open source
    • 28.7K GitHub stars
    • Developer tools
  3. Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.8K GitHub stars
    • Knowledge and memory
  4. Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  5. CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 468K GitHub stars
    • Developer tools

In short

  • gemini mcp add writes settings.json; project scope by default, -s user for everywhere.
  • One of command, url or httpUrl per server.
  • Narrow tools with includeTools/excludeTools; keep trust off.

What to try next

Share this lesson

Lesson 11 of 13 in this path

Words used in this lesson

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.

Get the next lesson

New Academy lessons are announced in the weekly AI-Powered email.