Skip to content

Commit cf36e77

Browse files
tobytoby
committed
docs: update README
1 parent 51ccba0 commit cf36e77

File tree

2 files changed

+72
-166
lines changed

2 files changed

+72
-166
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: 71 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,105 @@
11
# GitHub MCP Server
22

3-
GitHub MCP Server implemented in Go.
3+
The GitHub MCP Server is a Model Context Protocol (MCP) server that provides
4+
seamless integration with GitHub's APIs, enabling advanced automation and
5+
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+
with the permissions you want to give the MCP server. You can also install
17+
[Docker](https://www.docker.com/) to run the server in a container or build the
18+
binary from the repo.
1319

14-
You can either use a Docker image or build the binary from the repo.
20+
## Installation
1521

16-
#### Docker image
17-
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.
21-
22-
To make sure you can access the GitHub docker registry, run the following command:
22+
### Usage with VS Code
2323

2424
```bash
25-
docker pull ghcr.io/github/github-mcp-server:main
26-
```
25+
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}]}'
2726

28-
If the above command works, you are good to go.
29-
30-
#### Build from repo
31-
First, install `github-mcp-server` by cloning the repo and running the following command:
32-
33-
```bash
34-
go install ./cmd/github-mcp-server
3527
```
28+
When you start the server, VS Code will prompt for your token. On top of
29+
`servers`, you should see a `Start` link to start the server.
3630

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
41-
```
42-
43-
This will install the `github-mcp-server` binary in your `$GOPATH/bin` directory.
44-
45-
Find where the binary is installed by running:
31+
### Usage with Claude Desktop
4632

47-
```bash
48-
# note this assumes $GOPATH/bin is in your $PATH
49-
which github-mcp-server
33+
```json
34+
{
35+
"mcpServers": {
36+
"github": {
37+
"command": "docker",
38+
"args": [
39+
"run",
40+
"-i",
41+
"--rm",
42+
"-e",
43+
"GITHUB_PERSONAL_ACCESS_TOKEN",
44+
"ghcr.io/github/github-mcp-server:main"
45+
],
46+
"env": {
47+
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
48+
}
49+
}
50+
}
51+
}
5052
```
5153

52-
### Start VS Code Insiders
54+
### Build from source
5355

54-
Start VS Code Insiders and make sure you pass the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to the process.
56+
If you don't have Docker, you can build the binary from the repo and use the
57+
`github-mcp-server stdio` command with the `GITHUB_PERSONAL_ACCESS_TOKEN`
58+
environment variable set to your token.
5559

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:
60+
## GitHub Enterprise Server
5861

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

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

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

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

7073
```json
7174
{
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-
}
75+
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
76+
"TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
9277
}
9378
```
9479

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

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

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-
}
87+
```sh
88+
./github-mcp-server --export-translations
89+
cat github-mcp-server.json
11290
```
11391

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

117-
Try something like the following prompt to verify that it works:
96+
For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can
97+
set the following environment variable:
11898

119-
```
120-
I'd like to know more about my GitHub profile.
99+
```sh
100+
export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
121101
```
122102

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-
128103
## Tools
129104

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

356331
### Repository Content
357332

358-
- **Get Repository Content**
333+
- **Get Repository Content**
359334
Retrieves the content of a repository at a specific path.
360335

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

367-
- **Get Repository Content for a Specific Branch**
342+
- **Get Repository Content for a Specific Branch**
368343
Retrieves the content of a repository at a specific path for a given branch.
369344

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

377-
- **Get Repository Content for a Specific Commit**
352+
- **Get Repository Content for a Specific Commit**
378353
Retrieves the content of a repository at a specific path for a given commit.
379354

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

387-
- **Get Repository Content for a Specific Tag**
362+
- **Get Repository Content for a Specific Tag**
388363
Retrieves the content of a repository at a specific path for a given tag.
389364

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

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

400375
- **Template**: `repo://{owner}/{repo}/refs/pull/{pr_number}/head/contents{/path*}`
@@ -403,73 +378,3 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t
403378
- `repo`: Repository name (string, required)
404379
- `pr_number`: Pull request number (string, required)
405380
- `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)