How to Set Up MCP Servers in Gemini CLI (Step-by-Step)

Prerequisites

• Gemini CLI installed and authenticated (see Gemini CLI Getting Started)
• Node.js 18+ or Docker for npx- and Docker-based servers

What is MCP?

MCP (Model Context Protocol) lets Gemini CLI's agent use external tools — filesystem, GitHub, databases, search — through a standard interface. Gemini CLI reads your MCP config at startup and exposes each server's tools to the agent.

Enabling MCP in Gemini CLI

MCP servers are configured in settings.json under the top-level mcpServers object — the user file is ~/.gemini/settings.json and the project file is .gemini/settings.json. Gemini CLI does not use gemini.yaml for MCP.

You can add servers with the CLI, which writes to the chosen scope:

gemini mcp add -s user filesystem npx -y @modelcontextprotocol/server-filesystem .
gemini mcp add --transport http github https://api.githubcopilot.com/mcp/

Or edit settings.json directly:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Each server entry uses one transport property:

Optional fields include args, env, cwd, headers, timeout, trust, includeTools, and excludeTools.

Using ${VAR_NAME} or $VAR_NAME in env makes Gemini CLI resolve the value from your shell at launch — keep secrets out of the committed file. The GitHub server above uses OAuth discovery; Gemini CLI prompts you to authenticate on first connection.

Verifying Your Servers

1. Start Gemini CLI in your project
2. Ask the agent to use a tool from the server, e.g. "search the filesystem for README files" or "list my recent GitHub issues"
3. If a server failed to connect, check the session log for the startup error

Using MCP Tools in Gemini CLI

Once connected, the agent calls the server's tools like any built-in tool:

You: "Use the filesystem server to list the markdown files in docs/."

Agent: [calls the filesystem tool, returns the file list]

MCP tools are namespaced by server, so multiple servers can expose similarly named tools without conflict.

Security Considerations

• Least privilege — give servers only the credentials they need
• Keep secrets out of git — use ${VAR_NAME} interpolation so API keys resolve from your shell at launch
• Review server tools — an MCP server executes arbitrary commands on your machine
• Scoped servers — keep workspace-specific servers out of global config

Troubleshooting

Further Resources

• MCP Servers directory — pick servers that match your tools
• Gemini CLI Configuration — full settings.json reference
• Migration: Gemini CLI to Antigravity — if you're moving to Antigravity CLI
• MCP Setup in Cursor — the same concepts in Cursor

Sources

• https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
• https://github.com/github/github-mcp-server