-
Notifications
You must be signed in to change notification settings - Fork 1.8k
docs: Add Google Gemini CLI installation guide and integration #757
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
ipapapa
wants to merge
2
commits into
github:main
Choose a base branch
from
ipapapa:add-gemini-cli-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+337
−1
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,333 @@ | ||
| # Install GitHub MCP Server in Google Gemini CLI | ||
|
|
||
| ## Prerequisites | ||
| 1. Google Gemini CLI installed (see [Installation Options](#installation-options)) | ||
| 2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes | ||
| 3. For local installation: [Docker](https://www.docker.com/) installed and running | ||
|
|
||
| ## Installation Options | ||
|
|
||
| ### Option 1: npm (Global Installation) | ||
| ```bash | ||
| npm install -g @google/gemini-cli | ||
| ``` | ||
|
|
||
| ### Option 2: npx (No Installation Required) | ||
| ```bash | ||
| npx @google/gemini-cli | ||
| ``` | ||
|
|
||
| ### Option 3: Homebrew | ||
| ```bash | ||
| brew install gemini-cli | ||
| ``` | ||
|
|
||
| For more detailed installation instructions, see the [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli). | ||
|
|
||
| ## Authentication Setup | ||
|
|
||
| Before using Gemini CLI, you need to authenticate with Google: | ||
|
|
||
| ### Using Gemini API Key (Recommended) | ||
| 1. Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey) | ||
| 2. Set it as an environment variable: | ||
| ```bash | ||
| export GEMINI_API_KEY=your_api_key_here | ||
| ``` | ||
|
|
||
| ### Using Vertex AI | ||
| 1. Configure Google Cloud credentials for Vertex AI | ||
| 2. Set the project ID: | ||
| ```bash | ||
| export GOOGLE_CLOUD_PROJECT=your_project_id | ||
| ``` | ||
|
|
||
| ## GitHub MCP Server Configuration | ||
|
|
||
| ### Method 1: Remote Server (Recommended) | ||
|
|
||
| The simplest way is to use GitHub's hosted MCP server: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "httpUrl": "https://api.githubcopilot.com/mcp/", | ||
| "trust": true, | ||
| "headers": { | ||
| "Authorization": "Bearer ${GITHUB_PAT}" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Store your GitHub token in `~/.gemini/.env`: | ||
| ```bash | ||
| GITHUB_PAT=your_github_token_here | ||
| ``` | ||
|
|
||
| ### Method 2: Local Docker Setup (Alternative) | ||
|
|
||
| **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. | ||
|
|
||
| ### Docker Configuration | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "docker", | ||
| "args": [ | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "ghcr.io/github/github-mcp-server" | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Binary Configuration (Alternative) | ||
|
|
||
| If you prefer not to use Docker, you can build from source: | ||
|
|
||
| ```bash | ||
| # Clone and build the server | ||
| git clone https://github.com/github/github-mcp-server.git | ||
| cd github-mcp-server | ||
| go build -o github-mcp-server ./cmd/github-mcp-server | ||
| ``` | ||
|
|
||
| Then configure: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "/path/to/github-mcp-server", | ||
| "args": ["stdio"], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Installation Steps | ||
|
|
||
| ### Configuration File Location | ||
|
|
||
| Gemini CLI uses a settings JSON file to configure MCP servers: | ||
|
|
||
| - **Global configuration**: `~/.gemini/config.json` | ||
| - **Project-specific**: `.gemini/config.json` in your project directory | ||
|
|
||
| ### Setup Steps | ||
|
|
||
| 1. Create or edit your settings file with your chosen configuration from above | ||
| 2. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens) | ||
| 3. Save the file | ||
| 4. Restart Gemini CLI if it was running | ||
|
|
||
| ### Using Environment Variables (Recommended) | ||
|
|
||
| For better security, use environment variables: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "docker", | ||
| "args": [ | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "ghcr.io/github/github-mcp-server" | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Then set the environment variable: | ||
| ```bash | ||
| export GITHUB_PAT=your_github_pat | ||
| ``` | ||
|
|
||
| ## Configuration Options | ||
|
|
||
| ### Toolset Configuration | ||
|
|
||
| Enable specific GitHub API capabilities: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "docker", | ||
| "args": [ | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "-e", | ||
| "GITHUB_TOOLSETS", | ||
| "ghcr.io/github/github-mcp-server" | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT", | ||
| "GITHUB_TOOLSETS": "repos,issues,pull_requests,actions" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Read-Only Mode | ||
|
|
||
| For security, run the server in read-only mode: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "docker", | ||
| "args": [ | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "-e", | ||
| "GITHUB_READ_ONLY", | ||
| "ghcr.io/github/github-mcp-server" | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT", | ||
| "GITHUB_READ_ONLY": "1" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### GitHub Enterprise Support | ||
|
|
||
| For GitHub Enterprise Server or Enterprise Cloud with data residency: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "docker", | ||
| "args": [ | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "-e", | ||
| "GITHUB_HOST", | ||
| "ghcr.io/github/github-mcp-server" | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT", | ||
| "GITHUB_HOST": "https://your-github-enterprise.com" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Verification | ||
|
|
||
| After configuration, verify the installation: | ||
|
|
||
| 1. **Check MCP server status**: | ||
| ```bash | ||
| gemini --prompt "/mcp list" | ||
| ``` | ||
|
|
||
| 2. **List available tools**: | ||
| ```bash | ||
| gemini --prompt "/tools" | ||
| ``` | ||
|
|
||
| 3. **Test with a simple command**: | ||
| ```bash | ||
| gemini "List my GitHub repositories" | ||
| ``` | ||
|
|
||
| ## Usage Examples | ||
|
|
||
| Once configured, use natural language commands: | ||
|
|
||
| ```bash | ||
| # Repository operations | ||
| gemini "Show me the latest commits in microsoft/vscode" | ||
|
|
||
| # Issue management | ||
| gemini "Create an issue titled 'Bug report' in my-org/my-repo" | ||
|
|
||
| # Pull request operations | ||
| gemini "Review the latest pull request in my repository" | ||
|
|
||
| # Code analysis | ||
| gemini "Analyze the security alerts in my repositories" | ||
| ``` | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### Local Server Issues | ||
| - **Docker errors**: Ensure Docker Desktop is running | ||
| ```bash | ||
| docker --version | ||
| ``` | ||
| - **Image pull failures**: Try `docker logout ghcr.io` then retry | ||
| - **Docker not found**: Install Docker Desktop and ensure it's running | ||
|
|
||
| ### Authentication Issues | ||
| - **Invalid PAT**: Verify your GitHub PAT has correct scopes: | ||
| - `repo` - Repository operations | ||
| - `read:packages` - Docker image access (if using Docker) | ||
| - **Token expired**: Generate a new GitHub PAT | ||
|
|
||
| ### Configuration Issues | ||
| - **Invalid JSON**: Validate your configuration: | ||
| ```bash | ||
| cat ~/.gemini/config.json | jq . | ||
| ``` | ||
| - **MCP connection issues**: Check logs for connection errors: | ||
| ```bash | ||
| gemini --debug "test command" | ||
| ``` | ||
|
|
||
| ### Debug Mode | ||
|
|
||
| Enable debug mode for detailed logging: | ||
|
|
||
| ```bash | ||
| gemini --debug "Your command here" | ||
| ``` | ||
|
|
||
| ## Important Notes | ||
|
|
||
| - **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server) | ||
| - **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported) | ||
| - **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional) | ||
| - **Gemini CLI specifics**: Uses `mcpServers` key, supports both global and project configurations | ||
| - **Remote server method**: Preferred approach using GitHub's hosted MCP server at `https://api.githubcopilot.com/mcp/` | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question: should a guide on installing
gemini-clibe in here? or just a link to thegemini-cligithub page for instructions?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good question! I've kept a brief installation section for user convenience (just the basic commands for npm, npx, and Homebrew) but added a link to the https://github.com/google-gemini/gemini-cli for more detailed installation options. This way users get the essentials quickly but can dive deeper if needed. What do you think of this approach?