A Developer's Guide to Using MCP Servers with Gemini CLI

A Major Step for MCP: Google Gemini CLI Adds Native Support

In a significant validation of the Model-Context Protocol (MCP), Google’s powerful new Gemini CLI has incorporated native support for running external MCP servers. This development is a game-changer, allowing developers to extend the CLI’s capabilities far beyond its built-in tools by connecting it to any custom toolset, API, or database through a standardized protocol.

This guide will walk you through everything you need to know to leverage this powerful feature. We’ll cover how the integration works, how to configure your own servers, and a step-by-step tutorial using the official GitHub MCP server as a practical, real-world example.

The Power of MCP in Gemini CLI

By integrating MCP, Gemini CLI empowers developers with unparalleled flexibility. Instead of being locked into a predefined set of tools, you can now:

• Write Tools in Any Language: Build your server in Python, Node.js, Go, Rust, or any language that can communicate over standard I/O.
• Extend Core Functionality: Connect Gemini to proprietary internal APIs, legacy systems, or specialized data sources.
• Isolate Processes: Tools run in separate, managed processes, enhancing the security and stability of the main CLI application.
• Maintain State: Your MCP server can maintain persistent state, such as a database connection or in-memory cache, across multiple tool calls within a single session.

Configuring mcpServers in settings.json

The heart of this integration lies in the mcpServers object within your Gemini CLI settings file. You can define this in your global user settings (~/.gemini/settings.json) or, more commonly, in a project-specific file (.gemini/settings.json).

The structure is a dictionary where each key is a custom alias for your server.

{
  "mcpServers": {
    "<SERVER_NAME>": {
      "command": "string",
      "args": ["string"],
      "env": { "KEY": "VALUE" },
      "cwd": "string",
      "timeout": 10000,
      "trust": false
    }
  }
}

Configuration Properties Explained

• command (string, required): The executable to run to start the server (e.g., python, node, docker).
• args (array of strings, optional): A list of command-line arguments to pass to the command.
• cwd (string, optional): The working directory to run the command from. Highly recommended to ensure relative paths work correctly.
• env (object, optional): A dictionary of environment variables for the server’s process. You can pass through system variables using ${VAR_NAME} syntax, which is perfect for secrets.
• timeout (number, optional): The maximum time in milliseconds to wait for a response from the server before timing out.
• trust (boolean, optional): If true, all tool calls to this server will execute automatically without a confirmation prompt. Use this with extreme caution.

Practical Example: Integrating the GitHub MCP Server

Let’s walk through setting up the official GitHub MCP server. This server provides tools for interacting with GitHub repositories, like creating issues or commenting on pull requests.

Caution: Before using any third-party MCP server, ensure you trust its source and understand the tools it provides. Your use of third-party servers is at your own risk.

Step 1: Configure the Server in settings.json

In your project’s .gemini/settings.json file, add the following configuration.

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

This configuration tells Gemini CLI to:

• Define a server with the alias github.
• Use the docker command to run the official GitHub MCP server image.
• Pass an environment variable named GITHUB_PERSONAL_ACCESS_TOKEN into the container.
• Source the value for that variable from your system’s environment.

Step 2: Set Your GitHub Personal Access Token (PAT)

For the server to authenticate with GitHub, you must provide a PAT. Export it as an environment variable in your terminal.

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YourActualGitHubTokenHere"

To make this permanent, add this line to your shell profile (e.g., ~/.zshrc, ~/.bashrc) or use an .env file in your project root.

Important Security Note We strongly recommend using a fine-grained access token that is scoped only to the specific repositories you need to access. Using a classic, broadly-scoped token can create a security risk if it has access to both personal and sensitive private repositories.

Step 3: Launch Gemini CLI and Verify

Now, simply launch the Gemini CLI in your project’s directory. It will automatically read the configuration and start the Docker container in the background.

The tools from the server will now be available to the model, prefixed with the server alias (e.g., github__createIssue, github__getIssues). You can now make requests using natural language!

Example Prompt: “Find my repo called “my_repo_name” and add a todo list with these items…”

Best Practices for Custom Servers

• Always Use cwd: When running local scripts, always specify the cwd to avoid ambiguity with relative file paths.
• Test Your Command: Before adding it to settings.json, run your server’s start command directly in your terminal to ensure it works as expected.
• Secure Your Secrets: Use the env block with ${VAR_NAME} syntax to handle API keys. Store the actual secrets in an .env file and add .env to your .gitignore.
• Be Cautious with trust: true: Only enable automatic approval for tools you have written yourself and fully understand. For any tool that modifies files or makes external API calls, it is much safer to leave trust: false and approve calls manually.

Conclusion

The integration of MCP into Google’s Gemini CLI is more than just a new feature; it’s a powerful endorsement of a flexible, open standard for AI tool creation. It unlocks a new frontier of customization, allowing developers to securely connect Gemini to any system or workflow imaginable. By following this guide, you can start tapping into that power today, building more capable and context-aware AI assistants for your specific needs.

Happy building!