Gemini CLI is Google's open-source AI terminal that runs Gemini models from the command line. It added MCP support in 2025, which means you can connect it to the same servers that Claude Desktop and Cursor users have been running for months. If you already have MCP servers configured for another client, you are most of the way to making them work in Gemini CLI too. This guide walks through the exact configuration format, covers which server types are compatible, and explains where the setup differs from other AI clients you may already be familiar with.
What Is Gemini CLI and How Does It Use MCP Servers?
Gemini CLI is a terminal-based interface to Google's Gemini models. It runs locally, reads from a settings file, and passes tool calls to MCP servers the same way Claude Desktop and Cursor do. MCP servers act as a bridge between the Gemini model and external systems: a filesystem server lets Gemini read local files, a search server lets it fetch live web results, and a devtools server lets it interact with code repositories.
MCPFind indexes 10,212 MCP servers across 21 categories. The devtools category alone has 1,774 servers averaging 61 stars per server. Most of these servers were written for general MCP compatibility, not for a specific client, which means the majority of them work with Gemini CLI out of the box. Servers that use stdio transport (command-line subprocess model) and servers that expose an HTTP endpoint both work. The main constraint is the configuration file format.
One important note on scope: Gemini CLI supports MCP tool calls but does not currently support all MCP resource types. If a server you want to use exposes resources rather than tools, check the Gemini CLI documentation for the current resource support status before configuring it.
How Do You Add MCP Servers to Gemini CLI?
You add MCP servers by editing the settings.json file. For user-wide servers, the file lives at ~/.gemini/settings.json. For project-specific servers, create .gemini/settings.json in your project root. The project-level file takes precedence when both exist, which lets you have different server sets for different projects.
Here is the format for a stdio server and an HTTP server in the same config:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
},
"brave-search": {
"url": "https://mcp.brave.com",
"transport": "http",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}A few naming rules that catch people out: Gemini CLI does not allow underscores in server names. Use hyphens instead (brave-search not brave_search). The name you choose becomes the prefix for all tool names exposed by that server in the CLI session.
If a server requires environment variables (like API keys), add them explicitly in an env block inside the server entry. Gemini CLI does not inherit shell environment variables automatically the way some other clients do.
Which MCP Servers Are Compatible With Gemini CLI?
Any server that uses stdio or HTTP transport works with Gemini CLI. The vast majority of servers in the MCPFind devtools category (1,774 servers) use stdio, which means you can pull a server config from its MCPFind page and drop it directly into your settings.json without modification.
Servers using SSE (Server-Sent Events) transport may require an additional configuration step or a compatibility wrapper, depending on the version of Gemini CLI you are running. Check the release notes for your version if you encounter SSE servers that fail to connect.
For a curated starting point, the Docker MCP Toolkit includes over 220 pre-built servers that are tested for compatibility across major MCP clients including Gemini CLI. These servers cover filesystem access, GitHub, Playwright browser automation, and database connections. You configure them through the Docker Desktop UI rather than manually editing JSON, which reduces setup errors for complex server configurations.
Servers from the ai-ml category (755 servers, average 125.9 stars) that expose memory and search tools are also strong candidates for Gemini CLI workflows, especially if you are building multi-agent pipelines. For more on combining multiple MCP servers for agent workflows, see Building Multi-Agent Workflows With MCP.
How Is Gemini CLI MCP Config Different From Claude Desktop or Cursor?
The mcpServers object format is nearly identical across all three clients. The main differences are the config file location and a few client-specific validation rules.
Claude Desktop stores its config in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Cursor uses a settings UI that generates a similar JSON format in its config directory. Gemini CLI uses ~/.gemini/settings.json (or the project-level equivalent).
The naming restriction (no underscores) is Gemini CLI-specific. Claude Desktop and Cursor are more permissive about server name formats. If you are copying a config from Claude Desktop to Gemini CLI, scan the server names and replace any underscores with hyphens.
Gemini CLI also differs in how it exposes tools to the model. When a session starts, Gemini CLI loads all configured servers, discovers their tools, and makes them available in the session. Tools show up in the model's context under the server name as a prefix. Unlike some other clients, Gemini CLI does not let you selectively enable or disable individual tools from a server once the session is running.
For reference on how MCP configuration looks in Cursor, see How to Configure MCP Servers in Cursor. The comparison helps clarify where Gemini CLI follows the same conventions and where it diverges.
What Are Common Setup Issues When Running MCP Servers in Gemini CLI?
Three issues account for most failed Gemini CLI MCP setups.
The first is the underscore-in-name error described above. If a server fails to start and the error message mentions the server name, check for underscores and rename with hyphens. This is the most common configuration mistake and the easiest to fix.
The second issue is missing environment variables. Gemini CLI does not inherit your shell's environment automatically. If a server needs an OPENAI_API_KEY or similar variable, add an env block inside the server's config entry:
"my-server": {
"command": "npx",
"args": ["-y", "some-mcp-server"],
"env": {
"OPENAI_API_KEY": "your-key-here"
}
}The third issue is transport mismatch. If you copy a config that uses sse as the transport type, Gemini CLI may not recognize it in older versions. Switch to http as the transport type if available, or update Gemini CLI to the latest release which has improved SSE support.
For an introduction to MCP server concepts before diving into client-specific setup, read What Is MCP. For testing that your servers are responding correctly once configured, the MCP Inspector guide walks through the debugging process.
Adam Bush