How to Install and Manage Extensions in Gemini CLI

Gemini CLI's extension system transforms it from a standalone AI assistant into a customizable automation platform. Through Model Context Protocol (MCP) servers, you can add database connections, API integrations, custom tools, and specialized workflows that dramatically expand what Gemini can do in your development environment.

This guide walks you through finding, installing, managing, and troubleshooting extensions for Gemini CLI.

Understanding the Extension Architecture

Gemini CLI uses the Model Context Protocol (MCP) as its extension framework. MCP is an open standard that defines how AI agents communicate with external tools and services. This architecture provides several advantages:

• Portability: MCP servers work across multiple AI tools (Gemini CLI, Claude Code, Copilot CLI)
• Security: Extensions run as separate processes with controlled permissions
• Flexibility: Write extensions in any language that can speak the MCP protocol
• Discoverability: Standardized interface makes tools self-documenting

Each extension (MCP server) can expose three types of capabilities:

Finding Extensions

Official Sources

1. MCP Servers Directory (mcpservers.org): Community-maintained registry of MCP servers with installation instructions and compatibility notes.

2. Gemini CLI GitHub Repository: Check the /examples directory for official extension examples and recommended servers.

3. Google Cloud MCP Servers: Enterprise-grade extensions for Google Cloud services, BigQuery, Cloud Storage, and more.

Community Sources

• GitHub Topics: Search for mcp-server or gemini-cli-extension
• NPM Registry: Search for packages prefixed with mcp- or @mcp/
• PyPI: Search for FastMCP-based servers

Popular Extensions by Category

Installing Extensions

Method 1: Manual Configuration

Add extensions directly to your settings file at ~/.gemini/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/Users/yourname/projects"]
    }
  }
}

Method 2: Using Gemini CLI Commands

Gemini CLI provides built-in commands for managing extensions:

# Add a new extension
gemini mcp add filesystem npx -y @anthropic/mcp-filesystem /Users/yourname/projects

# List installed extensions
gemini mcp list

# Remove an extension
gemini mcp remove filesystem

Method 3: Using FastMCP Install

For Python-based extensions built with FastMCP:

# Install a local Python MCP server
fastmcp install gemini-cli ./my_tools.py

# Install from pip
pip install my-mcp-extension
fastmcp install gemini-cli my_mcp_extension

Verifying Installation

After adding an extension, verify it loaded correctly:

# Start Gemini CLI
gemini

# Inside the session, check connected servers
/mcp

You should see your extension listed with its available tools.

Managing Multiple Extensions

Project-Specific Extensions

Create .gemini/settings.json in your project root for project-specific extensions that override your global settings:

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "mcp-sqlite", "./data/project.db"]
    }
  }
}

This keeps project-specific tools isolated without cluttering your global configuration.

Enabling and Disabling Extensions

Temporarily disable extensions without removing their configuration:

# Disable an extension
gemini mcp disable filesystem

# Re-enable when needed
gemini mcp enable filesystem

Alternatively, add "disabled": true to the server configuration:

{
  "mcpServers": {
    "heavy-extension": {
      "command": "python",
      "args": ["heavy_server.py"],
      "disabled": true
    }
  }
}

Handling Tool Name Conflicts

When multiple extensions expose tools with the same name, Gemini CLI automatically prefixes them with the server alias:

• database__query (from "database" server)
• analytics__query (from "analytics" server)

You can explicitly call the prefixed version or use tool filtering to restrict which tools load.

Updating Extensions

NPM-Based Extensions

For extensions installed via npx, updates happen automatically (the -y flag fetches the latest version each run). For globally installed packages:

npm update -g @anthropic/mcp-filesystem

Python-Based Extensions

pip install --upgrade my-mcp-extension

Checking Extension Versions

Most MCP servers expose version information through the /mcp command. Look for version numbers in the server listing.

Troubleshooting Extension Issues

Extension Not Loading

1. Check the command path:

which npx  # or python, node, etc.

2. Test the server independently:

npx -y mcp-sqlite ./test.db

3. Enable debug mode:

gemini --debug

Permission Errors

MCP servers may need access to files or network resources. Check that:

• File paths in configuration are readable
• Network ports are not blocked by firewalls
• API keys have correct permissions

Slow Startup

Some extensions take time to initialize. Increase the timeout in your configuration:

{
  "mcpServers": {
    "slow-server": {
      "command": "python",
      "args": ["heavy_analysis.py"],
      "timeout": 120000
    }
  }
}

Creating Custom Extensions

Building your own extension is straightforward with FastMCP (Python) or the MCP TypeScript SDK.

Quick Python Example

from fastmcp import FastMCP

mcp = FastMCP("MyExtension")

@mcp.tool
def analyze_code(filepath: str) -> dict:
    """Analyze code quality metrics for a file."""
    # Your analysis logic here
    return {"complexity": 5, "lines": 100}

if __name__ == "__main__":
    mcp.run()

Install it:

fastmcp install gemini-cli my_extension.py

For comprehensive extension development guidance, see How to Configure MCP Integrations.

Security Considerations

Extension Permissions

MCP servers run as separate processes with access to your system. Before installing an extension:

• Review the source code when possible
• Check the maintainer reputation on GitHub/NPM
• Use tool filtering to restrict capabilities

Environment Variables

Never hardcode sensitive values. Use environment variable expansion:

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "$MY_API_KEY"
      }
    }
  }
}

Trust Settings

The trust: true option bypasses confirmation dialogs. Only use for servers you completely control:

{
  "mcpServers": {
    "my-internal-server": {
      "command": "python",
      "args": ["internal_tools.py"],
      "trust": true
    }
  }
}

Next Steps

• Browse the MCP Servers Directory for ready-to-use extensions
• Learn detailed MCP configuration in How to Configure MCP Integrations
• Explore the Gemini CLI GitHub repository for examples and documentation