docs: Add Google Gemini CLI installation guide and integration #757
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,157 @@ | ||
| # Install GitHub MCP Server in Google Gemini CLI | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| 1. Google Gemini CLI installed (see [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli)) | ||
| 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 | ||
|
|
||
| <details> | ||
| <summary><b>Storing Your PAT Securely</b></summary> | ||
| <br> | ||
|
|
||
| For security, avoid hardcoding your token. Create or update `~/.gemini/.env` (where `~` is your home or project directory) with your PAT: | ||
|
|
||
|
There was a problem hiding this comment. Probably lines 11 through 41 are best left out of this README., which pertains to github-mcp-server. Install instructions for Germini CLI should remain in the README for Gemini CLI. There was a problem hiding this comment. Good point about lines 11-41. I removed the Gemini CLI installation and authentication sections to keep this focused on GitHub MCP Server setup. This is also consistent with our other installation guides. |
||
| ```bash | ||
| # ~/.gemini/.env | ||
| GITHUB_PAT=your_token_here | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ## GitHub MCP Server Configuration | ||
|
There was a problem hiding this comment. The installation could be outdated with the main README.md file There was a problem hiding this comment. Added the note as requested: 26d9139 |
||
|
|
||
| MCP servers for Gemini CLI are configured in its settings JSON under an `mcpServers` key. | ||
|
|
||
| - **Global configuration**: `~/.gemini/settings.json` where `~` is your home directory | ||
| - **Project-specific**: `.gemini/settings.json` in your project directory | ||
|
|
||
| After securely storing your PAT, you can add the GitHub MCP server configuration to your settings file using one of the methods below. You may need to restart the Gemini CLI for changes to take effect. | ||
|
|
||
| ### Method 1: Remote Server (Recommended) | ||
|
|
||
| The simplest way is to use GitHub's hosted MCP server: | ||
|
|
||
| ```json | ||
| // ~/.gemini/settings.json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "httpUrl": "https://api.githubcopilot.com/mcp/", | ||
| "trust": true, | ||
| "headers": { | ||
| "Authorization": "Bearer $GITHUB_PAT" | ||
|
There was a problem hiding this comment. Oups good catch. I fixed it: f2e5ad7 |
||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Method 2: Local Docker | ||
|
|
||
| With docker running, you can run the GitHub MCP server in a container: | ||
|
|
||
| ```json | ||
| // ~/.gemini/settings.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" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Method 3: Binary | ||
|
|
||
| You can download the latest binary release from the [GitHub releases page](https://github.com/github/github-mcp-server/releases) or build it from source by running `go build -o github-mcp-server ./cmd/github-mcp-server`. | ||
|
|
||
| Then, replacing `/path/to/binary` with the actual path to your binary, configure Gemini CLI with: | ||
|
|
||
| ```json | ||
| // ~/.gemini/settings.json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "/path/to/binary", | ||
| "args": ["stdio"], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Verification | ||
|
|
||
| To verify that the GitHub MCP server has been configured, start Gemini CLI in your terminal with `gemini`, then: | ||
|
|
||
| 1. **Check MCP server status**: | ||
|
|
||
| ``` | ||
| /mcp list | ||
| ``` | ||
|
|
||
| ``` | ||
| ℹConfigured MCP servers: | ||
|
|
||
| 🟢 github - Ready (96 tools, 2 prompts) | ||
| Tools: | ||
| - github__add_comment_to_pending_review | ||
| - github__add_issue_comment | ||
| - github__add_sub_issue | ||
| ... | ||
| ``` | ||
|
|
||
| 2. **Test with a prompt** | ||
| ``` | ||
| List my GitHub 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/settings.json | jq . | ||
| ``` | ||
| - **MCP connection issues**: Check logs for connection errors: | ||
| ```bash | ||
| gemini --debug "test command" | ||
| ``` | ||
|
|
||
| ## 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) | ||
| - **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/` | ||
Oops, something went wrong.
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.
Or Podman. (https://podman.io)
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.
I have not used Podman but based on my quick check it has Docker command compatibility, so I have added it: 79e0782
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.
In case there is any doubt.... I use podman with this server and with gemini-cli, and it works great - no surprise here.