How can I add custom tools or extensions to Gemini CLI

Extending Gemini CLI with Custom Tools via MCP

Gemini CLI is designed to be extensible through the Model Context Protocol (MCP). MCP acts as a standardized way to connect external services and capabilities (tools) to Gemini CLI. By configuring MCP servers, Gemini CLI can integrate these external tools seamlessly into its AI-driven command and reasoning workflow.

- Setting up MCP Servers:
You start by configuring MCP servers in the Gemini CLI settings file, typically found at `~/.gemini/settings.json`. This JSON file configures what MCP servers to connect with, including connection details and authentication if needed.

- Using Existing or Custom MCP Servers:
Many existing MCP servers interface with popular services like GitHub, GitLab, Firebase, databases, or media generation. For truly custom functionality, you can create your own MCP servers using the MCP SDK available in languages like Python or TypeScript. This allows hosting any custom logic or tool as an MCP server.

- Configuring MCP Servers:
In the `settings.json` file, MCP servers are defined with their names, server types, connection commands or URLs, tokens for authentication, and any specialized parameters. Once configured, Gemini CLI will connect to these servers at startup.

- Discovery and Usage of Tools:
After connection, the MCP servers expose tools that Gemini CLI automatically discovers. You can list and describe these tools with commands like `/mcp` and `/mcp desc`. The AI agent then integrates them natively into its decision-making and execution flow, selecting tools as needed based on user prompts without manual intervention.

Creating Gemini CLI Extensions

Beyond MCP servers, Gemini CLI supports a higher-level concept called extensions, which bundle together MCP servers, context files, and custom commands to extend Gemini CLI functionality.

- Extension Location:
Extensions can reside in two primary locations: `/.gemini/extensions/` or `/.gemini/extensions/`. Gemini CLI loads all extensions found in both locations on startup, with workspace-specific extensions overriding home directory versions if name conflicts arise.

- Extension Structure:
Each extension is a directory named after the extension (e.g., `my-extension`) that contains a configuration file named `gemini-extension.json`. This JSON includes metadata and server configurations.

- gemini-extension.json Content:
Typical keys in this file include:

- `name`: Unique extension name.
- `version`: Extension version.
- `mcpServers`: A map of MCP servers configured by the extension, e.g., commands to launch custom MCP servers.
- `contextFileName`: Optional. Name of context file loaded as workspace context for the extension, defaults to `GEMINI.md`.
- `excludeTools`: Array specifying tools or tool commands to exclude, useful for blocking dangerous or undesired operations.

- Custom Commands in Extensions:
Extensions can provide custom slash commands by placing `.toml` command definition files inside a `commands/` subdirectory within the extension directory. These commands are defined similarly to user or project-specific commands.

- Merge Behavior:
When Gemini CLI starts, it merges extension configurations with the user's main settings and built-in tools, resolving conflicts by giving workspace settings priority.

Creating Custom Slash Commands with TOML Files

A flexible way to add reusable commands (tools) is by using `.toml` files as custom slash commands.

- Location:
Put TOML command files in `~/.gemini/commands/` for global commands or in the project-local `.gemini/commands/` directory.

- TOML Format:
These files define the command, prompt templates, and may incorporate arguments with placeholders like ``. They also support shell command execution within the prompt using syntax like `!{...}` to embed scripting.

- Usage:
These commands can be invoked directly in Gemini CLI through slash commands like `/mycommand `, enabling scripted workflows or integrations easily.

Running Custom Python Scripts and Shell Commands

- Since Gemini CLI supports running shell commands and scripts, you can trigger custom Python scripts or other programs as part of your MCP server or custom command workflows.

- For example, a Python script generating PDFs from Gemini CLI responses could be wrapped in an MCP server or executed as a shell command in a custom TOML command, enabling one-command generation workflows.

Integration with IDEs and Environment

- Gemini CLI extensions can also enhance integration with IDEs like VS Code by sharing workspace context (files, cursor location, selections), enabling AI-driven code assistance workflows.

- Extensions and MCP servers help integrate tailored workflows directly into the CLI or IDE environment, improving productivity and toolchain flexibility.

Summary of the Process to Add Custom Tools or Extensions

1. Decide the Scope of Custom Tool:
Determine if it is a simple custom command, a script, or a fully-fledged external service.

2. For Simple Custom Commands:
Create `.toml` files defining slash commands and place them in the appropriate commands folder.

3. For External Services or Complex Logic:
Develop an MCP server using the MCP SDK (supporting languages like Python or TypeScript) that exposes the tool capabilities via standardized API.

4. Configure MCP Server in `settings.json` or Extension:
Add the MCP server configuration entry (with command or URL) either directly in the user config `~/.gemini/settings.json` or inside a `gemini-extension.json` file within an extension directory.

5. Optionally Bundle in an Extension:
Package your MCP servers, custom commands, and context files into an extension directory structure under `.gemini/extensions/`.

6. Start or Restart Gemini CLI:
Gemini CLI loads all configurations and MCP servers on startup, auto-integrating custom tools.

7. Use and Verify Tools:
Use commands like `/mcp` and `/mcp desc` to confirm tool availability and interact with your custom additions.

Benefits of This Architecture

- Modularity: Tools run as separate MCP servers, making development independent and scalable.

- Dynamic Integration: Tools appear automatically in Gemini CLI workflows without hardcoding.

- Security and Control: Extensions can limit which tools or shell commands are allowed, preventing misuse.

- Reusability: Extensions package complete workflows, shareable across projects or teams.

- Community and Ecosystem: Many MCP servers and extensions are available or can be contributed, rapidly expanding Gemini CLI capabilities.

This architecture allows virtually any external tool, script, or service to be integrated into the Gemini CLI ecosystem, boosting productivity and customization.

***

This answer provides a thorough explanation of Gemini CLI custom tool and extension integration mechanisms, including MCP servers, extension packaging, custom commands, and scripting integration, meeting the length and detail requested. If desired, more specifics about MCP SDK usage or example configurations can be provided next.