Skip to content

Commit ff86293

Browse files
LuluBeatsonLuluBeatson
committed
Refactor Gemini CLI install guide
1 parent 39db9e7 commit ff86293

File tree

1 file changed

+86
-225
lines changed

1 file changed

+86
-225
lines changed

‎docs/installation-guides/install-gemini-cli.md‎

Lines changed: 86 additions & 225 deletions
Original file line numberDiff line numberDiff line change
@@ -1,296 +1,157 @@
11
# Install GitHub MCP Server in Google Gemini CLI
22

33
## Prerequisites
4+
45
1. Google Gemini CLI installed (see [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli))
56
2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
6-
3. For local installation: [Docker](https://www.docker.com/) or [Podman](https://podman.io) installed and running
7-
8-
## GitHub MCP Server Configuration
7+
3. For local installation: [Docker](https://www.docker.com/) installed and running
98

10-
### Method 1: Remote Server (Recommended)
9+
<details>
10+
<summary><b>Storing Your PAT Securely</b></summary>
11+
<br>
1112

12-
The simplest way is to use GitHub's hosted MCP server:
13+
For security, avoid hardcoding your token. Create or update `~/.gemini/.env` (where `~` is your home or project directory) with your PAT:
1314

14-
```json
15-
{
16-
"mcpServers": {
17-
"github": {
18-
"httpUrl": "https://api.githubcopilot.com/mcp/",
19-
"trust": true,
20-
"headers": {
21-
"Authorization": "Bearer YOUR_GITHUB_PAT"
22-
}
23-
}
24-
}
25-
}
26-
```
27-
28-
Create or update `~/.gemini/.env` with your environment variables:
2915
```bash
3016
# ~/.gemini/.env
31-
GITHUB_PAT=ghp_sample_sample_sample
32-
GOOGLE_CLOUD_PROJECT=my-gcp-project
33-
GEMINI_API_KEY=AIzSamplelBQGwHw-62R598eI-HFOWd4Ol847g
34-
```
35-
36-
### Method 2: Local Docker Setup (Alternative)
37-
38-
### Docker Configuration
39-
40-
```json
41-
{
42-
"mcpServers": {
43-
"github": {
44-
"command": "docker",
45-
"args": [
46-
"run",
47-
"-i",
48-
"--rm",
49-
"-e",
50-
"GITHUB_PERSONAL_ACCESS_TOKEN",
51-
"ghcr.io/github/github-mcp-server"
52-
],
53-
"env": {
54-
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
55-
}
56-
}
57-
}
58-
}
59-
```
60-
61-
### Binary Configuration (Alternative)
62-
63-
If you prefer not to use Docker, you can build from source:
64-
65-
```bash
66-
# Clone and build the server
67-
git clone https://github.com/github/github-mcp-server.git
68-
cd github-mcp-server
69-
go build -o github-mcp-server ./cmd/github-mcp-server
70-
```
71-
72-
Then configure:
73-
74-
```json
75-
{
76-
"mcpServers": {
77-
"github": {
78-
"command": "/path/to/github-mcp-server",
79-
"args": ["stdio"],
80-
"env": {
81-
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
82-
}
83-
}
84-
}
85-
}
17+
GITHUB_PAT=your_token_here
8618
```
8719

88-
## Installation Steps
20+
</details>
8921

90-
### Configuration File Location
22+
## GitHub MCP Server Configuration
9123

92-
Gemini CLI uses a settings JSON file to configure MCP servers:
24+
MCP servers for Gemini CLI are configured in its settings JSON under an `mcpServers` key.
9325

94-
- **Global configuration**: `~/.gemini/settings.json`
26+
- **Global configuration**: `~/.gemini/settings.json` where `~` is your home directory
9527
- **Project-specific**: `.gemini/settings.json` in your project directory
9628

97-
### Setup Steps
29+
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.
9830

99-
1. Create or edit your settings file with your chosen configuration from above
100-
2. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens)
101-
3. Save the file
102-
4. Restart Gemini CLI if it was running
103-
104-
### Using Environment Variables (Recommended)
31+
### Method 1: Remote Server (Recommended)
10532

106-
For better security, use environment variables:
33+
The simplest way is to use GitHub's hosted MCP server:
10734

10835
```json
36+
// ~/.gemini/settings.json
10937
{
110-
"mcpServers": {
111-
"github": {
112-
"command": "docker",
113-
"args": [
114-
"run",
115-
"-i",
116-
"--rm",
117-
"-e",
118-
"GITHUB_PERSONAL_ACCESS_TOKEN",
119-
"ghcr.io/github/github-mcp-server"
120-
],
121-
"env": {
122-
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
123-
}
38+
"mcpServers": {
39+
"github": {
40+
"httpUrl": "https://api.githubcopilot.com/mcp/",
41+
"trust": true,
42+
"headers": {
43+
"Authorization": "Bearer $GITHUB_PAT"
44+
}
45+
}
12446
}
125-
}
12647
}
12748
```
12849

129-
Then add the environment variable to `~/.gemini/.env`:
130-
```bash
131-
GITHUB_PAT=your_github_pat
132-
```
133-
134-
## Configuration Options
50+
### Method 2: Local Docker
13551

136-
### Toolset Configuration
137-
138-
Enable specific GitHub API capabilities:
52+
With docker running, you can run the GitHub MCP server in a container:
13953

14054
```json
55+
// ~/.gemini/settings.json
14156
{
142-
"mcpServers": {
143-
"github": {
144-
"command": "docker",
145-
"args": [
146-
"run",
147-
"-i",
148-
"--rm",
149-
"-e",
150-
"GITHUB_PERSONAL_ACCESS_TOKEN",
151-
"-e",
152-
"GITHUB_TOOLSETS",
153-
"ghcr.io/github/github-mcp-server"
154-
],
155-
"env": {
156-
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT",
157-
"GITHUB_TOOLSETS": "repos,issues,pull_requests,actions"
158-
}
57+
"mcpServers": {
58+
"github": {
59+
"command": "docker",
60+
"args": [
61+
"run",
62+
"-i",
63+
"--rm",
64+
"-e",
65+
"GITHUB_PERSONAL_ACCESS_TOKEN",
66+
"ghcr.io/github/github-mcp-server"
67+
],
68+
"env": {
69+
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
70+
}
71+
}
15972
}
160-
}
16173
}
16274
```
16375

164-
### Read-Only Mode
165-
166-
For security, run the server in read-only mode:
167-
168-
```json
169-
{
170-
"mcpServers": {
171-
"github": {
172-
"command": "docker",
173-
"args": [
174-
"run",
175-
"-i",
176-
"--rm",
177-
"-e",
178-
"GITHUB_PERSONAL_ACCESS_TOKEN",
179-
"-e",
180-
"GITHUB_READ_ONLY",
181-
"ghcr.io/github/github-mcp-server"
182-
],
183-
"env": {
184-
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT",
185-
"GITHUB_READ_ONLY": "1"
186-
}
187-
}
188-
}
189-
}
190-
```
76+
### Method 3: Binary
19177

192-
### GitHub Enterprise Support
78+
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`.
19379

194-
For GitHub Enterprise Server or Enterprise Cloud with data residency:
80+
Then, replacing `/path/to/binary` with the actual path to your binary, configure Gemini CLI with:
19581

19682
```json
83+
// ~/.gemini/settings.json
19784
{
198-
"mcpServers": {
199-
"github": {
200-
"command": "docker",
201-
"args": [
202-
"run",
203-
"-i",
204-
"--rm",
205-
"-e",
206-
"GITHUB_PERSONAL_ACCESS_TOKEN",
207-
"-e",
208-
"GITHUB_HOST",
209-
"ghcr.io/github/github-mcp-server"
210-
],
211-
"env": {
212-
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT",
213-
"GITHUB_HOST": "https://your-github-enterprise.com"
214-
}
85+
"mcpServers": {
86+
"github": {
87+
"command": "/path/to/binary",
88+
"args": ["stdio"],
89+
"env": {
90+
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
91+
}
92+
}
21593
}
216-
}
21794
}
21895
```
21996

22097
## Verification
22198

222-
After configuration, verify the installation:
99+
To verify that the GitHub MCP server has been configured, start Gemini CLI in your terminal with `gemini`, then:
223100

224101
1. **Check MCP server status**:
225-
```bash
226-
gemini --prompt "/mcp list"
227-
```
228-
229-
2. **List available tools**:
230-
```bash
231-
gemini --prompt "/tools"
232-
```
233-
234-
3. **Test with a simple command**:
235-
```bash
236-
gemini "List my GitHub repositories"
237-
```
238-
239-
## Usage Examples
240102

241-
Once configured, use natural language commands:
103+
```
104+
/mcp list
105+
```
242106
243-
```bash
244-
# Repository operations
245-
gemini "Show me the latest commits in microsoft/vscode"
246-
247-
# Issue management
248-
gemini "Create an issue titled 'Bug report' in my-org/my-repo"
107+
```
108+
ℹConfigured MCP servers:
249109
250-
# Pull request operations
251-
gemini "Review the latest pull request in my repository"
110+
🟢 github - Ready (96 tools, 2 prompts)
111+
Tools:
112+
- github__add_comment_to_pending_review
113+
- github__add_issue_comment
114+
- github__add_sub_issue
115+
...
116+
```
252117
253-
# Code analysis
254-
gemini "Analyze the security alerts in my repositories"
255-
```
118+
2. **Test with a prompt**
119+
```
120+
List my GitHub repositories
121+
```
256122
257123
## Troubleshooting
258124
259125
### Local Server Issues
126+
260127
- **Docker errors**: Ensure Docker Desktop is running
261-
```bash
262-
docker --version
263-
```
128+
```bash
129+
docker --version
130+
```
264131
- **Image pull failures**: Try `docker logout ghcr.io` then retry
265132
- **Docker not found**: Install Docker Desktop and ensure it's running
266133
267-
### Authentication Issues
134+
### Authentication Issues
135+
268136
- **Invalid PAT**: Verify your GitHub PAT has correct scopes:
269-
- `repo` - Repository operations
270-
- `read:packages` - Docker image access (if using Docker)
137+
- `repo` - Repository operations
138+
- `read:packages` - Docker image access (if using Docker)
271139
- **Token expired**: Generate a new GitHub PAT
272140
273141
### Configuration Issues
142+
274143
- **Invalid JSON**: Validate your configuration:
275-
```bash
276-
cat ~/.gemini/settings.json | jq .
277-
```
144+
```bash
145+
cat ~/.gemini/settings.json | jq .
146+
```
278147
- **MCP connection issues**: Check logs for connection errors:
279-
```bash
280-
gemini --debug "test command"
281-
```
282-
283-
### Debug Mode
284-
285-
Enable debug mode for detailed logging:
286-
287-
```bash
288-
gemini --debug "Your command here"
289-
```
148+
```bash
149+
gemini --debug "test command"
150+
```
290151
291152
## Important Notes
292153
293154
- **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server)
294155
- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported)
295156
- **Gemini CLI specifics**: Uses `mcpServers` key, supports both global and project configurations
296-
- **Remote server method**: Preferred approach using GitHub's hosted MCP server at `https://api.githubcopilot.com/mcp/`
157+
- **Remote server method**: Preferred approach using GitHub's hosted MCP server at `https://api.githubcopilot.com/mcp/`

0 commit comments

Comments
 (0)