ContextQMD
Back to Gemini Cli

Set up an MCP server

docs/cli/tutorials/mcp-setup.md

0.41.13.2 KB
Original Source

Set up an MCP server

Connect Gemini CLI to your external databases and services. In this guide, you'll learn how to extend Gemini CLI's capabilities by installing the GitHub MCP server and using it to manage your repositories.

Prerequisites

  • Gemini CLI installed.
  • Docker: Required for this specific example (many MCP servers run as Docker containers).
  • GitHub token: A Personal Access Token (PAT) with repo permissions.

How to prepare your credentials

Most MCP servers require authentication. For GitHub, you need a PAT.

  1. Create a fine-grained PAT.
  2. Grant it Read access to Metadata and Contents, and Read/Write access to Issues and Pull Requests.
  3. Store it in your environment:

macOS/Linux

bash
export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."

Windows (PowerShell)

powershell
$env:GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."

How to configure Gemini CLI

You tell Gemini about new servers by editing your settings.json.

  1. Open ~/.gemini/settings.json (or the project-specific .gemini/settings.json).
  2. Add the mcpServers block. This tells Gemini: "Run this docker container and talk to it."
json
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server:latest"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}
<!-- prettier-ignore -->

[!NOTE] The command is docker, and the rest are arguments passed to it. We map the local environment variable into the container so your secret isn't hardcoded in the config file.

How to verify the connection

Restart Gemini CLI. It will automatically try to start the defined servers.

Command: /mcp list

You should see: ✓ github: docker ... - Connected

If you see Disconnected or an error, check that Docker is running and your API token is valid.

How to use the new tools

Now that the server is running, the agent has new capabilities ("tools"). You don't need to learn special commands; just ask in natural language.

Scenario: Listing pull requests

Prompt: List the open PRs in the google/gemini-cli repository.

The agent will:

  1. Recognize the request matches a GitHub tool.
  2. Call mcp_github_list_pull_requests.
  3. Present the data to you.

Scenario: Creating an issue

Prompt: Create an issue in my repo titled "Bug: Login fails" with the description "See logs".

Troubleshooting

  • Server won't start? Try running the docker command manually in your terminal to see if it prints an error (for example, "image not found").
  • Tools not found? Run /mcp reload to force the CLI to re-query the server for its capabilities.

Next steps