This article guides you end-to-end to design, develop, test, and publish a custom Gemini CLI extension. You’ll learn extension structure (gemini-extension.json, GEMINI.md), how to bundle MCP servers/tools, add custom slash commands, run a local MCP server for development, link and install your extension into Gemini CLI, best practices for security, testing, and distribution, plus a working example you can adapt.
Pre-requisite
Before diving into building your own custom extension for the Gemini CLI, make sure you’ve completed the Gemini CLI Hands-On Codelab. That guide walks you through the basics of installing the Gemini CLI, setting up your environment, and using core commands to interact with Gemini models. It’s essential groundwork—you’ll need that understanding to follow along as we extend the CLI’s functionality with custom plugins. Once you’re comfortable running Gemini from the command line and understand how its command structure works, you’ll be ready to move on to creating your own extension.
Why build a Gemini CLI extension?
Gemini CLI is an open-source AI agent that runs in your terminal. Extensions are packaged add-ons that let Gemini CLI understand and interact with your specific tools, APIs, and domains. Use cases:
Add domain knowledge (internal docs, API reference)
Expose custom tools via MCP (Model Context Protocol) for the agent to call
Provide prebuilt prompts, flows, and slash commands for common tasks
Ship integrations for your product (databases, monitoring, cloud services)
An extension makes your workflows reproducible and shareable across teams — instead of configuring settings manually, a single repo installs everything.
High-level architecture
A Gemini CLI extension typically bundles:
gemini-extension.json— manifest describing the extension, MCP servers, commands, versioning, and install instructions.GEMINI.md— optional human + agent-facing guidance (context, recommended prompts, usage notes).One or more MCP servers (local or remote) — expose tools (APIs/actions/data) that the agent can invoke.
Prompts / flows / example use cases — to speed onboarding.
Optional UI or scripts (helper CLI commands) to aid devs.
At runtime, Gemini CLI reads the extension, registers MCP servers, makes tools discoverable to the agent, and adds slash commands and prompts to the CLI environment.
Anatomy of a minimal extension
1) gemini-extension.json (manifest)
A minimal manifest tells Gemini CLI where to find MCP servers, the extension name, version, and other metadata.
{
"name": "example-org/gemini-extension-hello",
"version": "0.1.0",
"description": "Hello extension — exposes a sample MCP tool and demo prompts",
"mcp_servers": [
{
"name": "hello-mcp",
"url": "http://localhost:8080",
"description": "Local MCP server exposing `say_hello` tool"
}
],
"commands": [
{
"name": "hello.run",
"description": "Runs the hello flow",
"usage": "gemini /hello.run"
}
],
"repository": "https://github.com/example-org/gemini-extension-hello"
}
2) GEMINI.md
This markdown file gives context that the agent uses (and that humans will read). Include example prompts, configuration notes, English descriptions of tools and side effects.
# Hello Extension
This extension exposes a `say_hello` tool for demo purposes.
## Example prompt for agent
> Use the `say_hello` tool if the user asks for a greeting. Provide concise greeting and ask a follow-up question.
## Tools
- `say_hello(name: string)` — returns a greeting string.
3) MCP server (tool provider)
MCP servers describe and expose tools via the Model Context Protocol. They run separately (can be local during dev or remote). They should provide a machine-readable tool manifest and endpoints for execution.
A tiny Node/Express + MCP pseudo-server (illustrative):
// server.js (very simplified pseudo code)
const express = require('express');
const app = express();
app.use(express.json());
app.get('/mcp/manifest', (req,res)=> {
res.json({
tools: [
{
name: "say_hello",
description: "Return greeting for given name",
inputs: [{name: "name", type: "string", required: true}]
}
]
});
});
app.post('/mcp/run/say_hello', (req,res) => {
const {name} = req.body;
res.json({result: `Hello, ${name}! 👋`});
});
app.listen(8080, ()=>console.log('MCP server running on 8080'));
Production MCP servers typically implement authentication, OpenTelemetry tracing, error handling, rate limiting, and provide a richer tool schema.
Step-by-step development workflow
Step 1 — Plan the extension
Decide what your extension will add: tools, prompts, commands, or a combination.
Identify side effects: will tools write to systems, modify infra, or send emails?
Determine auth: how will the MCP server authenticate requests (API keys, OAuth, Workload Identity Federation)?
Step 2 — Scaffold repo
Create a GitHub repo with:
gemini-extension.jsonGEMINI.mdmcp/(MCP server code)prompts/directory with example promptsREADME.mddescribing install/use
Step 3 — Implement MCP server
Expose a manifest endpoint (
/mcp/manifestor as required by your MCP implementation).Implement
runendpoints for tools (/mcp/run/<tool_name>).Include an OpenAPI-style description for tools (input/output schemas).
Add authentication hooks.
Step 4 — Add extension manifest and docs
Fill gemini-extension.json and GEMINI.md. Make docs clear about:
How to set environment variables
Required Google Cloud / provider roles (if any)
Security considerations
Step 5 — Local development: linking & testing
Gemini CLI usually supports a command to link a local extension (e.g., gemini extensions link ./path-to-extension), or you can install via the repo URL:
Join the conversation! Your thoughts help the community grow.