MCP Server Configuration
Configure Model Context Protocol (MCP) servers to extend Gemini CLI with additional capabilities.
What is MCP?
Model Context Protocol (MCP) is a standardized way to connect AI models with external tools and data sources. MCP servers provide Gemini CLI with access to:
- • File system operations
- • Database connections
- • Web APIs and services
- • Development tools and environments
- • Custom business logic
Configuration File Location and Format
Gemini CLI reads its configuration from a JSON file. The default paths by operating system are:
# macOS and Linux
~/.config/gemini-cli/config.json
# Windows
%APPDATA%\gemini-cli\config.json
You can override the path by setting the GEMINI_CLI_CONFIG environment variable to an absolute file path. This is useful for managing multiple profiles — for example, a personal config and a work config — or for switching between project-specific configurations in your shell setup.
The file must be valid JSON. A missing or malformed file causes Gemini CLI to fall back to defaults and print a warning. Create the directory first if it does not exist:
mkdir -p ~/.config/gemini-cli && touch ~/.config/gemini-cli/config.json
Configuration Fields Explained
Every field in config.json is optional except for apiKey (unless you authenticate via the CLI). Here is a reference for all fields relevant to MCP:
apiKey
Your Gemini API key. Alternatively, set the GEMINI_API_KEY environment variable to avoid storing the key in a file. The environment variable takes precedence.
mcpServers
An object where each key is a human-readable server name and each value is a server definition object. Server names appear in tool call logs so choose descriptive names like filesystem,postgres, or github.
mcpServers[name].command
The executable to run. Examples: npx,node,python3, or an absolute path to a binary. The command is resolved relative to the user's PATH.
mcpServers[name].args
An array of string arguments passed to the command. For npm-based servers the first argument is typically the package name (e.g., @modelcontextprotocol/server-filesystem), followed by any server-specific options.
mcpServers[name].env
An object of additional environment variables to inject into the server process. Use"VAR": "${SHELL_VAR}" syntax to reference variables already set in your shell, or hardcode values for non-sensitive configuration. Never hardcode secrets here; use references to shell environment variables instead.
mcpServers[name].cwd
The working directory in which the server process is started. Defaults to the user's home directory. Set this to a project root if the server relies on relative paths to find project files.
Basic Configuration
Configure MCP servers in your Gemini CLI configuration file:
# ~/.config/gemini-cli/config.json
{ "apiKey": "your-api-key", "mcpServers": { "filesystem": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/path/to/directory"] } } }
Multi-Server Configuration Examples
A production setup typically connects several MCP servers at once: one for file access, one for database queries, one for version control operations, and so on. All servers listed inmcpServers are started when Gemini CLI launches and are available as tools for the entire session.
Development Environment — File System + Git + Browser
{ "apiKey": "${GEMINI_API_KEY}", "mcpServers": { "filesystem": { "command": "npx", "args": [ "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects" ] }, "git": { "command": "npx", "args": ["@modelcontextprotocol/server-git"], "cwd": "/Users/yourname/projects/my-repo" }, "puppeteer": { "command": "npx", "args": ["@modelcontextprotocol/server-puppeteer"] } } }
Data Engineering — File System + PostgreSQL + Fetch
{ "apiKey": "${GEMINI_API_KEY}", "mcpServers": { "filesystem": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/data"], "cwd": "/data" }, "postgres": { "command": "npx", "args": [ "@modelcontextprotocol/server-postgres", "${DATABASE_URL}" ], "env": { "DATABASE_URL": "${DATABASE_URL}" } }, "fetch": { "command": "npx", "args": ["@modelcontextprotocol/server-fetch"] } } }
Custom Local Server
If you have written your own MCP server (for example, one that wraps an internal company API), point the command andargs at your local script:
{ "apiKey": "${GEMINI_API_KEY}", "mcpServers": { "internal-api": { "command": "node", "args": ["./mcp-servers/internal-api-server.js"], "cwd": "/Users/yourname/projects/my-repo", "env": { "INTERNAL_API_TOKEN": "${INTERNAL_API_TOKEN}", "API_BASE_URL": "https://api.internal.company.com" } } } }
Environment Variables and Secret Management
Never store raw API keys, database passwords, or tokens in config.json. The file sits in your home directory and is often included in backups or synced to cloud storage. Use one of the following patterns instead:
- Shell variable interpolation — Write
"${MY_SECRET}"as the value. Gemini CLI resolves it from the shell environment at startup. Export secrets in your.zshrcor.bashrc(not in.zprofileor.bash_profile, which are only read for login shells). - macOS Keychain — Store the secret in Keychain and retrieve it in a wrapper script:
export DATABASE_URL=$(security find-generic-password -a "$USER" -s "my-db-url" -w)
- 1Password / Bitwarden CLI — Use
op run --orbw-run --as the wrapper command to inject secrets at runtime without ever writing them to disk. - dotenv files — Place secrets in a
.envfile in your home directory (not the project root) and source it in your shell profile:source ~/.env.privateAdd*.env.privateto your global.gitignore.
Common Configuration Errors and Fixes
Error: MCP server failed to start
This usually means the command or path in args is wrong. Test the command manually in your terminal first:
npx @modelcontextprotocol/server-filesystem /tmp
If the server starts and waits for input, the config is correct. If it prints an error, fix the command before adding it to config.json.
Error: Tool not found / tool unavailable
Confirm the server is listed in mcpServers with the correct key name. Restart Gemini CLI after any config change — changes are not hot-reloaded. Also verify that the server process has not crashed by checking your terminal for stderr output.
Error: Permission denied when accessing files
The MCP server process runs with the permissions of the current user. If Gemini CLI itself was launched with sudo, the server may have elevated permissions that cause unexpected behavior. Run as a non-root user and grant the necessary directory permissions to your user account instead.
Error: JSON parse error in config.json
Validate your config file with a JSON linter before starting Gemini CLI. The most common mistake is a trailing comma after the last property:
# Validate JSON syntax
cat ~/.config/gemini-cli/config.json | python3 -m json.tool
Environment variable not resolved
Variable substitution only works at the top level of env values. Confirm the variable is exported in the same shell session where you run Gemini CLI. Use echo $MY_VAR to verify it is set before launching.
Complete MCP Integration Guide
Read our end-to-end guide on building a custom MCP server, connecting it to Gemini CLI, and using it to automate real workflows — including a working example with a PostgreSQL server and a GitHub integration.
Read: Gemini CLI MCP Configuration and Integration Guide →Frequently Asked Questions
Where is the Gemini CLI MCP configuration file located?
The main configuration file is ~/.config/gemini-cli/config.json on Linux and macOS. On Windows it is located at%APPDATA%\gemini-cli\config.json. You can override the path by setting theGEMINI_CLI_CONFIG environment variable to an absolute path.
Can I run multiple MCP servers at the same time?
Yes. The mcpServers object inconfig.json accepts any number of named server entries. Each entry is started as a separate process. Give each server a unique key — for example, "filesystem", "database", and "github" — and Gemini CLI will manage all of them concurrently.
How do I pass secrets like API keys to an MCP server without hardcoding them?
Use the env field inside the server entry. Reference environment variables with ${VAR_NAME} syntax, e.g."env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }The shell variable is resolved at startup. Never put raw secrets in config.json.
My MCP server starts but Gemini CLI says the tool is unavailable. What should I check?
First, run the server command manually in your terminal to verify it starts without errors. Second, check that the args array paths are absolute and the files exist. Third, look for permission errors — the server process must have read/write access to the target directories. Finally, confirm the server implements the MCP protocol version Gemini CLI expects.
Can I use a local or custom-built MCP server instead of an npm package?
Yes. Set command tonode and pointargs at your local script:["./mcp-servers/my-server.js", "--port", "3000"]Any process that speaks the MCP protocol over stdio works. You can also use Python:"command": "python3", "args": ["./mcp-servers/my_server.py"]