MCP Servers & Extensions

What is MCP?

The Three MCP Primitives

Gemini CLI uses all three primitives. During a conversation, it can call Tools autonomously, expose Resources as context, and surface Prompts as slash-command shortcuts.

Adding MCP Servers to Gemini CLI

MCP servers are configured in GEMINI.md — the same memory file that holds project context. The ## MCP Servers section is a YAML block that Gemini CLI parses at startup.

# Install a community MCP server globally via npm
npm install -g @modelcontextprotocol/server-postgres

# Or install project-locally
npm install --save-dev @modelcontextprotocol/server-filesystem

# Verify the server binary is available
npx @modelcontextprotocol/server-postgres --help

# Install a community MCP server globally via npm
npm install -g @modelcontextprotocol/server-postgres

# Or install project-locally
npm install --save-dev @modelcontextprotocol/server-filesystem

# Verify the server binary is available
npx @modelcontextprotocol/server-postgres --help

GEMINI.md Configuration

Add an ## MCP Servers block to your project's GEMINI.md file:

## MCP Servers

- name: postgres
  command: npx
  args: ["@modelcontextprotocol/server-postgres"]
  env:
    DATABASE_URL: ${DATABASE_URL}

- name: filesystem
  command: npx
  args: ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]

- name: github
  command: npx
  args: ["@modelcontextprotocol/server-github"]
  env:
    GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}

Verifying Installed Tools

# Start Gemini CLI and list all loaded tools
gemini
# Inside the session:
/tools

# Or check from the command line (non-interactive)
gemini -p "/tools" | Out-String

# Start Gemini CLI and list all loaded tools
gemini
# Inside the session:
/tools

# Or check from the command line (non-interactive)
gemini -p "/tools"

Expected /tools output after configuring the postgres and github servers:

Available tools (15):

Built-in:
  shell_execute       Execute shell commands
  file_read           Read file contents
  file_write          Write or modify files
  web_search          Search the web

MCP — postgres:
  query               Run a SELECT query against the configured database
  list_tables         List all tables in the database
  describe_table      Get schema for a specific table

MCP — github:
  create_issue        Create a GitHub issue
  list_issues         List issues with filters
  create_pull_request Create a pull request
  get_pull_request    Get PR details and diff
  list_commits        List recent commits

Google + Partner Extension Catalog

Google maintains a curated set of first-party and partner-verified MCP extensions. These are pre-authenticated, production-tested integrations that go beyond community servers.

Extension Catalog

The Google Workspace Extension

Installation and Authentication

# Install the Workspace extension
gemini extensions install google-workspace

# Output: Installing google-workspace...
#   Requesting OAuth scopes:
#     - https://www.googleapis.com/auth/gmail.readonly
#     - https://www.googleapis.com/auth/gmail.send
#     - https://www.googleapis.com/auth/drive.readonly
#     - https://www.googleapis.com/auth/calendar.events
#   Opening browser for authorization...
#   ✓ Authorized. Token stored in: ~\.gemini\extensions\google-workspace\token.json

# Verify installation
gemini extensions list

# Install the Workspace extension
gemini extensions install google-workspace

# Output: Installing google-workspace...
#   Requesting OAuth scopes:
#     - https://www.googleapis.com/auth/gmail.readonly
#     - https://www.googleapis.com/auth/gmail.send
#     - https://www.googleapis.com/auth/drive.readonly
#     - https://www.googleapis.com/auth/calendar.events
#   Opening browser for authorization...
#   ✓ Authorized. Token stored in: ~/.gemini/extensions/google-workspace/token.json

# Verify installation
gemini extensions list

Once installed, Gemini gains over 100 built-in agent skills spanning all Workspace products:

Cross-Service Example: Gmail + Slack

The real power emerges when Workspace skills combine with other MCP servers. With both google-workspace and a Slack MCP server installed:

Send a summary of today's unread emails from my product@company.com address
to the #product-updates Slack channel. Group by sender. Include action items.

Gemini's execution chain (invisible to the user):

1. Calls Gmail list_messages with filter to:product@company.com is:unread newer_than:1d
2. Calls Gmail get_message for each message to read full content
3. Generates a grouped summary with action items extracted from each thread
4. Calls Slack MCP post_message to #product-updates with the formatted summary

OAuth 2.0 and Remote MCP Servers

Not all MCP servers run locally. Remote MCP servers are hosted services that expose their capabilities over HTTPS using Server-Sent Events (SSE)An HTTP-based protocol where the server pushes a stream of events to the client over a persistent connection. MCP uses SSE as the transport for remote servers, allowing the server to send tool responses back to Gemini CLI asynchronously over a single long-lived HTTP connection. transport. Accessing them requires OAuth 2.0 for authentication.

## MCP Servers

- name: linear
  type: remote
  url: https://mcp.linear.app/sse
  auth:
    type: oauth2
    client_id: ${LINEAR_MCP_CLIENT_ID}
    client_secret: ${LINEAR_MCP_CLIENT_SECRET}
    scopes: ["issues:read", "issues:write", "teams:read"]

- name: notion
  type: remote
  url: https://api.notion.com/mcp/sse
  auth:
    type: bearer
    token: ${NOTION_INTEGRATION_TOKEN}

Environment Variable Sanitization

By default, Gemini CLI passes all environment variables to MCP server processes. This is a security risk if you install an untrusted community server — it could read your GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, or DATABASE_URL.

## MCP Servers

# Untrusted community server — restrict env access
- name: community-analytics
  command: npx
  args: ["community-analytics-mcp-server"]
  env:
    # Only pass the vars this server legitimately needs
    ANALYTICS_API_KEY: ${ANALYTICS_API_KEY}
    NODE_ENV: production
  # Prevent inheriting the parent shell's environment entirely
  env_inherit: false

Building a Custom MCP Server

FastMCP in 20 Lines — Python

# Install: pip install fastmcp
from fastmcp import FastMCP
import httpx

mcp = FastMCP("company-data-server")

@mcp.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer by ID from the internal CRM API."""
    with httpx.Client() as client:
        response = client.get(
            f"https://crm.internal/api/customers/{customer_id}",
            headers={"Authorization": f"Bearer {os.environ['CRM_API_KEY']}"}
        )
        response.raise_for_status()
        return response.json()

@mcp.tool()
def list_open_orders(customer_id: str, limit: int = 10) -> list[dict]:
    """List open orders for a customer, newest first. Max 100."""
    limit = min(limit, 100)  # enforce ceiling
    with httpx.Client() as client:
        r = client.get(
            f"https://orders.internal/api/orders",
            params={"customer_id": customer_id, "status": "open", "limit": limit}
        )
        r.raise_for_status()
        return r.json()["orders"]

if __name__ == "__main__":
    mcp.run()  # stdio transport (default)

// Install: npm install @modelcontextprotocol/sdk
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "company-data-server", version: "1.0.0" });

server.tool(
  "get_customer",
  "Look up a customer by ID from the internal CRM API",
  { customer_id: z.string().describe("The customer UUID") },
  async ({ customer_id }) => {
    const res = await fetch(
      `https://crm.internal/api/customers/${customer_id}`,
      { headers: { Authorization: `Bearer ${process.env.CRM_API_KEY}` } }
    );
    if (!res.ok) throw new Error(`CRM returned ${res.status}`);
    const data = await res.json();
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Connect your new server to Gemini CLI via GEMINI.md:

## MCP Servers

- name: company-data
  command: python
  args: ["tools/mcp_server.py"]
  env:
    CRM_API_KEY: ${CRM_API_KEY}
  env_inherit: false

Knowledge Check