Gemini CLI: Add MCP Servers and Install Extensions

Gemini CLI reads MCP servers from settings.json, in two places: ~/.gemini/settings.json for every project, and .gemini/settings.json inside a project for that repo only.

1. Add a server by hand

{
  "mcpServers": {
    "local-tools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "cwd": "./tools",
      "env": { "API_KEY": "$MY_API_TOKEN" },
      "timeout": 30000,
      "excludeTools": ["delete_record"]
    }
  }
}

What it does: launches a stdio server from ./tools, expands $MY_API_TOKEN from your environment so no secret lands in the file, gives it a 30-second request timeout (the default is 600000 ms), and blocks one tool. includeTools is the opposite — an allowlist — and excludeTools wins when both are present.

Each entry needs exactly one of three keys: command for stdio, httpUrl for a streamable HTTP endpoint, or url for SSE. Remote entries also take headers.

2. Or add it with one command

gemini mcp add --transport http company-api https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

What it does: writes the entry for you. -t is short for --transport and accepts stdio (default), sse or http; -H is short for --header; -e KEY=value sets an env var. Scope is --scope project by default — pass --scope user to make it global.

3. Check it

/mcp

What it does: shows every configured server, whether it connected, and the tools and prompts it exposes. /mcp list gives the short status view, /mcp auth handles OAuth for servers that need a browser login, and /mcp enable <name> / /mcp disable <name> toggle one without editing the file.

4. Install an extension

Extensions package prompts, MCP servers, custom commands and sub-agents as one installable unit:

gemini extensions install https://github.com/gemini-cli-extensions/workspace

What it does: clones the extension into .gemini/extensions/<name>/, where its gemini-extension.json manifest declares its mcpServers and tool filters. gemini extensions list confirms it installed and is enabled. Other install sources exist — run gemini extensions --help for the current flags rather than guessing.

Note that the trust: true option on a server skips confirmation prompts for its tool calls. Set it only for servers you control.

---

Next: first steps with Gemini CLI or build your own MCP server in Python.