How to add an MCP server to Gemini CLI

Checked against Gemini CLI's documentation on Oct 26, 2026. Commands and config blocks are generated from the same install data as each listing page.

1. 1. Choose a server and see what it needs

   Gemini CLI keeps a server in the project by default, or for your user with -s user. Decide which fits before you add anything.

   • Playwright MCP: runs locally, no key needed.
   • Figma MCP Server: hosted, connect by URL, no key needed.
   • Firecrawl MCP Server: runs locally, can take FIRECRAWL_API_KEY.
   • Where Gemini CLI can keep a server: project (.gemini/settings.json, the default) and user (~/.gemini/settings.json with -s user).

2. 2. Add a local server (Playwright MCP)

   Playwright MCP runs locally. The command gives the server name, then npx and its arguments after a double dash, and the settings entry holds the same command and args as separate keys.

   gemini mcp add --scope user playwright-mcp npx -- -y @playwright/mcp@0.0.82

   Copy

   {
     "mcpServers": {
       "playwright-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "@playwright/mcp@0.0.82"
         ]
       }
     }
   }

   Copy

3. 3. Add a remote server (Figma MCP Server)

   Figma MCP Server is hosted. The command passes --transport http with the URL, while the settings entry uses the key httpUrl.

   gemini mcp add --scope user --transport http figma https://mcp.figma.com/mcp

   Copy

   {
     "mcpServers": {
       "figma": {
         "httpUrl": "https://mcp.figma.com/mcp"
       }
     }
   }

   Copy

   • If the server uses OAuth, run /mcp auth inside Gemini CLI.

4. 4. Keep API keys out of the file (Firecrawl MCP Server)

   Firecrawl MCP Server can take FIRECRAWL_API_KEY. The command passes it with -e, and the settings entry refers to $FIRECRAWL_API_KEY, which Gemini CLI resolves when it loads settings.

   gemini mcp add --scope user -e FIRECRAWL_API_KEY=YOUR_FIRECRAWL_API_KEY firecrawl-mcp-server npx -- -y firecrawl-mcp@3.34.1

   Copy

   {
     "mcpServers": {
       "firecrawl-mcp-server": {
         "command": "npx",
         "args": [
           "-y",
           "firecrawl-mcp@3.34.1"
         ],
         "env": {
           "FIRECRAWL_API_KEY": "$FIRECRAWL_API_KEY"
         }
       }
     }
   }

   Copy

   export FIRECRAWL_API_KEY="paste-your-value-here"

   Copy

   • Values in settings.json resolve $VAR and ${VAR} from your shell or a .env file at load time, and an unset variable becomes an empty string. Variables whose names look like keys or tokens are removed from a server's inherited environment unless you list them in its env block.
   • The command stores the value in settings.json. The file version refers to an environment variable, which Gemini CLI resolves when it loads settings; a variable that is not set becomes an empty string.
   • FIRECRAWL_API_KEY (optional): Your API key for Firecrawl.

5. 5. Restart or reload if the server does not appear

   Use this step if the server does not appear. The notes cover starting a new session, trusting a folder with gemini trust, and a notice in the Gemini CLI docs about Antigravity CLI.

   • The docs do not say whether a restart is needed after gemini mcp add. Discovery runs at startup, so start a new session to be safe.
   • A stdio server shows DISCONNECTED in a folder you have not trusted; run gemini trust for that folder.
   • Every page of the Gemini CLI docs carries a notice that, for unpaid-tier and Google One users, Gemini CLI was replaced by Antigravity CLI on June 18th, 2026.

gemini mcp list