231 Extending The Gemini Cli

title: “2.3.1: Extending the Gemini CLI” tags: [“kb”]

2.3.1: Extending the Gemini CLI

Summary: The Gemini CLI’s functionality can be extended through two primary mechanisms: Gemini CLI Extensions and MCP (Model Context Protocol) Servers. Extensions are for simple commands and configuration, while MCP servers provide a powerful way to integrate external tools and services. This knowledge chunk provides the necessary details for an agent to implement both.

Details:

1. Gemini CLI Extensions

Extensions are self-contained packages for adding custom commands and configuring the CLI.

• Location: Loaded from <workspace>/.gemini/extensions and ~/.gemini/extensions. Workspace extensions take precedence.
• Structure: An extension is a directory containing a gemini-extension.json file and an optional commands/ subdirectory.
• gemini-extension.json:
  • This file defines the extension’s properties.
  • Example:

    {
      "name": "my-extension",
      "version": "1.0.0",
      "mcpServers": {
        "my-server": {
          "command": "node my-server.js"
        }
      },
      "contextFileName": "GEMINI.md",
      "excludeTools": ["run_shell_command"]
    }

• Custom Commands:
  • Place TOML files in a commands/ subdirectory to define new slash commands.
  • Example hello.toml:

    [command]
    name = "hello"
    description = "Prints a greeting"
    prompt = "Say hello to the user"

  • Conflict Resolution: If an extension command conflicts with a user or project command, it is automatically prefixed with the extension name (e.g., /my-extension.hello).

2. MCP (Model Context Protocol) Servers

MCP Servers are standalone applications that expose external tools to the Gemini CLI.

• Communication: They can communicate with the CLI via three transport mechanisms:
  1. Stdio: The CLI spawns the server as a subprocess.
  2. SSE (Server-Sent Events): The CLI connects to a URL endpoint.
  3. HTTP Streaming: The CLI connects to an HTTP endpoint.
• Configuration:
  • Servers are configured in the mcpServers object in a settings.json file (either global or in a project/extension).
  • The CLI provides helper commands: gemini mcp add, gemini mcp list, gemini mcp remove.
  • Example Stdio Configuration:

    {
      "mcpServers": {
        "pythonTools": {
          "command": "python",
          "args": ["-m", "my_mcp_server"],
          "cwd": "./mcp-servers/python",
          "env": { "API_KEY": "$MY_API_TOKEN" },
          "trust": false
        }
      }
    }

• Capabilities:
  • Expose Tools: The primary function is to expose custom tools to the Gemini model.
  • Expose Prompts: Servers can also define pre-canned prompts that become available as slash commands.
  • Rich Content: Tools can return rich, multi-part content, including text, images, and audio.
• Debugging:
  • The /mcp command can be used to check the status and discovered tools of all configured servers.

Key Artifacts:

• Source Research: research/002-extending-gemini-cli.md
• Gemini CLI Documentation: The docs/ directory in the Gemini CLI repository, specifically extension.md and tools/mcp-server.md.