Skip to content

Commit a4e05c9

Browse files
tobytoby
committed
docs: update README
1 parent 450fa65 commit a4e05c9

File tree

2 files changed

+75
-161
lines changed

2 files changed

+75
-161
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
.idea
2+
cmd/github-mcp-server/github-mcp-server

‎README.md

Lines changed: 74 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,113 @@
11
# GitHub MCP Server
22

3-
GitHub MCP Server implemented in Go.
3+
The GitHub MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
4+
server that provides seamless integration with GitHub APIs, enabling advanced
5+
automation and interaction capabilities for developers and tools.
46

5-
## Setup
7+
## Use Cases
68

7-
Create a GitHub Personal Access Token with the appropriate permissions
8-
and set it as the GITHUB_PERSONAL_ACCESS_TOKEN environment variable.
9+
- Automating GitHub workflows and processes.
10+
- Extracting and analyzing data from GitHub repositories.
11+
- Building AI powered tools and applications that interact with GitHub's ecosystem.
912

10-
## Testing in VS Code Insiders
13+
## Prerequisites
1114

12-
### Requirements
15+
[Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new).
16+
The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools.
1317

14-
You can either use a Docker image or build the binary from the repo.
18+
To learn more about access tokens, please check out the [documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
1519

16-
#### Docker image
20+
To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed.
1721

18-
As of now, this repo is private, and hence the docker image is not available publicly. To pull it,
19-
you need to make sure you can access the GitHub docker registry. See [this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic)
20-
for more details.
22+
## Installation
2123

22-
To make sure you can access the GitHub docker registry, run the following command:
24+
### Usage with VS Code
2325

24-
```bash
25-
docker pull ghcr.io/github/github-mcp-server:main
26-
```
26+
Install the GitHub MCP server into VS Code by clicking here:
2727

28-
If the above command works, you are good to go.
28+
[<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%25%7B%22name%22%3A%22github%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%20%22-i%22%2C%20%22--rm%22%2C%20%22-e%22%2C%20%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%20%22ghcr.io%2Fgithub%2Fgithub-mcp-server%3Amain%22%5D%2C%20%22env%22%3A%20%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%20%22%24%7Binput%3Agithub-pat%7D%22%7D%2C%20%22inputs%22%3A%20%5B%7B%20%22id%22%3A%20%22github-pat%22%2C%20%22type%22%3A%20%22promptString%22%2C%20%22description%22%3A%20%22Github%20Personal%20Access%20Token%22%2C%20%22password%22%3A%20true%7D%5D%7D)
2929

30-
#### Build from repo
31-
First, install `github-mcp-server` by cloning the repo and running the following command:
30+
Or run this command in your terminal:
3231

3332
```bash
34-
go install ./cmd/github-mcp-server
35-
```
33+
code --add-mcp '{"name":"github","command":"docker","args":["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:main"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github-pat}"}, "inputs": [{ "id": "github-pat", "type": "promptString", "description": "Github Personal Access Token", "password": true}]}'
3634

37-
If you don't want to clone the repo, you can run:
38-
39-
```bash
40-
GOPRIVATE=github.com/github go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest
4135
```
36+
VS Code is now configured and will prompt for your token the first time you use agent mode.
4237

43-
This will install the `github-mcp-server` binary in your `$GOPATH/bin` directory.
38+
### Usage with Claude Desktop
4439

45-
Find where the binary is installed by running:
46-
47-
```bash
48-
# note this assumes $GOPATH/bin is in your $PATH
49-
which github-mcp-server
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:main"
52+
],
53+
"env": {
54+
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
55+
}
56+
}
57+
}
58+
}
5059
```
5160

52-
### Start VS Code Insiders
61+
### Build from source
5362

54-
Start VS Code Insiders and make sure you pass the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to the process.
63+
If you don't have Docker, you can use `go` to build the binary in the
64+
`cmd/github-mcp-server` directory, and use the `github-mcp-server stdio`
65+
command with the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable set to
66+
your token.
5567

56-
One way to do this is to make sure that [you can run VS code from your terminal](https://code.visualstudio.com/docs/setup/mac#_launch-vs-code-from-the-command-line) and
57-
start it with the following command:
68+
## GitHub Enterprise Server
5869

59-
```bash
60-
export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here
61-
code-insiders
62-
```
70+
The flag `--gh-host` and the environment variable `GH_HOST` can be used to set
71+
the GitHub Enterprise Server hostname.
6372

64-
Another way is to set the environment variable in your shell configuration file (e.g., `.bashrc`, `.zshrc`, etc.).
73+
## i18n / Overriding Descriptions
6574

66-
Create a new file `.vscode/mcp.json` and provide this configuration:
75+
The descriptions of the tools can be overridden by creating a
76+
`github-mcp-server-config.json` file in the same directory as the binary.
6777

68-
If you are using the docker image, use this configuration:
78+
The file should contain a JSON object with the tool names as keys and the new
79+
descriptions as values. For example:
6980

7081
```json
7182
{
72-
"inputs": [
73-
{
74-
"id": "github-pat",
75-
"type": "promptString",
76-
"description": "Github Personal Access Token",
77-
"password": true,
78-
}
79-
],
80-
"servers": {
81-
"github-mcp-server": {
82-
"type": "stdio",
83-
"command": "docker",
84-
"args": [
85-
"run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:main"
86-
],
87-
"env": {
88-
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github-pat}"
89-
}
90-
}
91-
}
83+
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
84+
"TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
9285
}
9386
```
9487

95-
When you start the server, VS Code will prompt for your token, as indicated by `${input:github-pat}`.
88+
You can create an export of the current translations by running the binary with
89+
the `--export-translations` flag.
9690

97-
If you built the binary from the repo use this configuration:
91+
This flag will preserve any translations/overrides you have made, while adding
92+
any new translations that have been added to the binary since the last time you
93+
exported.
9894

99-
```json
100-
{
101-
"mcp": {
102-
"inputs": [ ],
103-
"servers": {
104-
"mcp-github-server": {
105-
"command": "path-to-your/github-mcp-server",
106-
"args": ["stdio"],
107-
"env": { }
108-
}
109-
}
110-
}
111-
}
95+
```sh
96+
./github-mcp-server --export-translations
97+
cat github-mcp-server-config.json
11298
```
11399

114-
Right on top of `servers`, you should see a `Start` link to start the server.
100+
You can also use ENV vars to override the descriptions. The environment
101+
variable names are the same as the keys in the JSON file, prefixed with
102+
`GITHUB_MCP_` and all uppercase.
115103

104+
For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can
105+
set the following environment variable:
116106

117-
Try something like the following prompt to verify that it works:
118-
119-
```
120-
I'd like to know more about my GitHub profile.
107+
```sh
108+
export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
121109
```
122110

123-
## GitHub Enterprise Server
124-
125-
The flag `--gh-host` and the environment variable `GH_HOST` can be used to set the GitHub Enterprise Server hostname.
126-
127-
128111
## Tools
129112

130113
### Users
@@ -355,7 +338,7 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
355338

356339
### Repository Content
357340

358-
- **Get Repository Content**
341+
- **Get Repository Content**
359342
Retrieves the content of a repository at a specific path.
360343

361344
- **Template**: `repo://{owner}/{repo}/contents{/path*}`
@@ -364,7 +347,7 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
364347
- `repo`: Repository name (string, required)
365348
- `path`: File or directory path (string, optional)
366349

367-
- **Get Repository Content for a Specific Branch**
350+
- **Get Repository Content for a Specific Branch**
368351
Retrieves the content of a repository at a specific path for a given branch.
369352

370353
- **Template**: `repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}`
@@ -374,7 +357,7 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
374357
- `branch`: Branch name (string, required)
375358
- `path`: File or directory path (string, optional)
376359

377-
- **Get Repository Content for a Specific Commit**
360+
- **Get Repository Content for a Specific Commit**
378361
Retrieves the content of a repository at a specific path for a given commit.
379362

380363
- **Template**: `repo://{owner}/{repo}/sha/{sha}/contents{/path*}`
@@ -384,7 +367,7 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
384367
- `sha`: Commit SHA (string, required)
385368
- `path`: File or directory path (string, optional)
386369

387-
- **Get Repository Content for a Specific Tag**
370+
- **Get Repository Content for a Specific Tag**
388371
Retrieves the content of a repository at a specific path for a given tag.
389372

390373
- **Template**: `repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}`
@@ -394,7 +377,7 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
394377
- `tag`: Tag name (string, required)
395378
- `path`: File or directory path (string, optional)
396379

397-
- **Get Repository Content for a Specific Pull Request**
380+
- **Get Repository Content for a Specific Pull Request**
398381
Retrieves the content of a repository at a specific path for a given pull request.
399382

400383
- **Template**: `repo://{owner}/{repo}/refs/pull/{pr_number}/head/contents{/path*}`
@@ -403,73 +386,3 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
403386
- `repo`: Repository name (string, required)
404387
- `pr_number`: Pull request number (string, required)
405388
- `path`: File or directory path (string, optional)
406-
407-
## Standard input/output server
408-
409-
```sh
410-
go run cmd/github-mcp-server/main.go stdio
411-
```
412-
413-
E.g:
414-
415-
Set the PAT token in the environment variable and run:
416-
417-
```sh
418-
script/get-me
419-
```
420-
421-
And you should see the output of the GitHub MCP server responding with the user information.
422-
423-
```sh
424-
GitHub MCP Server running on stdio
425-
{
426-
"jsonrpc": "2.0",
427-
"id": 3,
428-
"result": {
429-
"content": [
430-
{
431-
"type": "text",
432-
"text": "{\"login\":\"juruen\",\"id\" ... }
433-
}
434-
]
435-
}
436-
}
437-
438-
```
439-
440-
## i18n / Overriding descriptions
441-
442-
The descriptions of the tools can be overridden by creating a github-mcp-server.json file in the same directory as the binary.
443-
The file should contain a JSON object with the tool names as keys and the new descriptions as values.
444-
For example:
445-
446-
```json
447-
{
448-
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
449-
"TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
450-
}
451-
```
452-
453-
You can create an export of the current translations by running the binary with the `--export-translations` flag.
454-
This flag will preserve any translations/overrides you have made, while adding any new translations that have been added to the binary since the last time you exported.
455-
456-
```sh
457-
./github-mcp-server --export-translations
458-
cat github-mcp-server.json
459-
```
460-
461-
You can also use ENV vars to override the descriptions. The environment variable names are the same as the keys in the JSON file,
462-
prefixed with `GITHUB_MCP_` and all uppercase.
463-
464-
For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can set the following environment variable:
465-
466-
```sh
467-
export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
468-
```
469-
470-
## TODO
471-
472-
Testing
473-
474-
- Integration tests
475-
- Blackbox testing: ideally comparing output to Anthropic's server to make sure that this is a fully compatible drop-in replacement.

0 commit comments

Comments
 (0)