MCP Integration Tutorial
Learn how to extend Gemini CLI capabilities by integrating Model Context Protocol (MCP) servers.
What is the Model Context Protocol?
The Model Context Protocol (MCP) is an open standard that defines how AI models communicate with external tools and data sources. Think of it as a universal plugin system for AI assistants. Without MCP, Gemini CLI can only read files you explicitly pipe to it. With MCP, it can autonomously call any tool a connected server exposes — reading from a database, running shell commands, querying an API, or searching the web — all while answering a single natural-language prompt.
MCP servers are independent processes that expose a set of named tools. Each tool has a description and a JSON Schema for its parameters. When Gemini decides a tool is relevant to your request, it calls the tool, receives the result, and incorporates it into its response. This loop can repeat multiple times within a single conversation turn — for example, listing a directory, reading a file, then writing an updated version.
MCP is transport-agnostic: servers communicate over stdio (standard input/output) by default, but can also use HTTP with Server-Sent Events. The stdio transport is the easiest to set up and works well for local development tools.
Popular MCP Servers
The MCP ecosystem already includes dozens of ready-to-use servers. Here are the most useful ones for software development workflows:
| Server | npm Package | What it provides |
|---|---|---|
| filesystem | @modelcontextprotocol/server-filesystem | Read, write, move, and list files on your local machine |
| git | @modelcontextprotocol/server-git | Read git history, diff commits, and inspect repository metadata |
| sqlite | @modelcontextprotocol/server-sqlite | Query and mutate a local SQLite database with natural language |
| brave-search | @modelcontextprotocol/server-brave-search | Web search via the Brave Search API (requires a free API key) |
| puppeteer | @modelcontextprotocol/server-puppeteer | Control a headless browser to scrape and interact with web pages |
| postgres | @modelcontextprotocol/server-postgres | Connect to a PostgreSQL database and execute read-only queries |
Setup and Configuration
1. Install MCP Server
Install the MCP server packages you want to use. You can install them globally or locally in your project. Global installation makes them available from any directory, which is convenient for general-purpose servers like filesystem and git.
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-git
2. Configure Gemini CLI
Register each server with Gemini CLI using the gemini mcp add command. The first argument is the server alias (used to reference it later), and the remaining arguments are the command to start the server process.
gemini mcp add filesystem npx @modelcontextprotocol/server-filesystem ./
gemini mcp add git npx @modelcontextprotocol/server-git .
Each registration writes an entry to the Gemini CLI config file at ~/.gemini/config.json. You can also edit this file directly:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
"env": {}
},
"git": {
"command": "npx",
"args": ["@modelcontextprotocol/server-git", "."],
"env": {}
}
}
}
3. Test Integration
Verify the servers are connected and Gemini can use them by running a prompt that requires tool use. With the filesystem server active, Gemini can list directories, read files, and write new files autonomously:
# Should list all files in the current directory
gemini "List all files in my project directory"
# Should read the git log and summarize recent changes
gemini "Show me the git history for the last week"
# Verify server status
gemini mcp list
Debugging Connection Issues
When a MCP server fails to connect, Gemini CLI will either silently omit its tools or print an error depending on the failure mode. Here are the most common issues and how to diagnose them.
Server not found or not installed
If the server package is not installed, the process fails to start. Verify the package exists in your global npm directory:
npm list -g @modelcontextprotocol/server-filesystem
# If missing:
npm install -g @modelcontextprotocol/server-filesystem
Permission denied on the target path
The filesystem server restricts access to the path you pass as an argument. Make sure the path is readable by your current user and that you use an absolute path:
# Use absolute path, not relative
gemini mcp add filesystem npx @modelcontextprotocol/server-filesystem "$(pwd)"
View server logs
Enable debug logging by setting the GEMINI_DEBUG environment variable, which prints all MCP stdio messages to stderr:
GEMINI_DEBUG=mcp gemini "List files"
Advanced MCP Usage
Custom MCP Server Creation
If the available community servers do not cover your use case, you can build a custom server in TypeScript or Python using the official MCP SDK. A typical use case might be exposing an internal REST API, wrapping a proprietary database driver, or providing Gemini access to your company's documentation system.
The scaffold command creates a complete TypeScript project with the MCP SDK pre-configured. Implement your tools in src/index.ts, then build and register the server:
npm create mcp-server my-custom-server
cd my-custom-server
# Edit src/index.ts with your custom tool logic
npm run build
gemini mcp add custom node ./dist/index.js
# Test your custom tool
gemini "Use the custom tool to fetch my data"
Frequently Asked Questions
What is the Model Context Protocol (MCP)?
MCP is an open standard that defines how AI models communicate with external tools and data sources. It lets Gemini CLI call filesystem APIs, databases, web services, and custom tools without any hardcoded integration code. Think of it as a universal plugin system.
Do MCP servers run locally or in the cloud?
Most MCP servers run as local processes on your machine and communicate with Gemini CLI over stdio. Your data never leaves your machine unless the MCP server itself makes outbound network calls (for example, a web-search server). This makes MCP safe to use with proprietary codebases.
How do I verify that a MCP server is connected?
Run gemini mcp list to see all registered servers and their status. A "connected" indicator means the server process started successfully. If the status shows "error", enable debug logging with GEMINI_DEBUG=mcp gemini ... to see the raw stdio messages.
Can I build my own MCP server?
Yes. The MCP SDK is available for TypeScript and Python. Run npm create mcp-server my-server to scaffold a new TypeScript server, implement your tool handlers, build it, and register it with gemini mcp add my-server node ./dist/index.js.
How many MCP servers can I register?
There is no hard limit on the number of registered servers. However, each server is started as a separate process when Gemini CLI launches, so registering many servers increases startup time and memory usage. Keep only the servers you actively use in your configuration.