- Notifications
You must be signed in to change notification settings - Fork943
docs: update README#58
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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,2 @@ | ||
| .idea | ||
| cmd/github-mcp-server/github-mcp-server |
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 |
|---|---|---|
| @@ -1,130 +1,113 @@ | ||
| # GitHub MCP Server | ||
| The GitHub MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) | ||
| server that provides seamless integration with GitHub APIs, enabling advanced | ||
| automation and interaction capabilities for developers and tools. | ||
| ##Use Cases | ||
| - Automating GitHub workflows and processes. | ||
| - Extracting and analyzing data from GitHub repositories. | ||
| - Building AI powered tools and applications that interact with GitHub's ecosystem. | ||
| ##Prerequisites | ||
| [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new). | ||
| The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools. | ||
| 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). | ||
| To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed. | ||
| ## Installation | ||
| ### Usage with VS Code | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. does this require that they have completed the prerequisite step above to have it installed? what about commands to get it running? | ||
| Install the GitHub MCP server into VS Code by clicking here: | ||
| [<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) | ||
| Or run this command in your terminal: | ||
| ```bash | ||
| 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}]}' | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. is would be good to explain what this is doing There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. It's part of the VS Code config. For this one, I modeled it on the Playwright readme:https://github.com/microsoft/playwright-mcp?tab=readme-ov-file#installation-in-vs-code | ||
| ``` | ||
| VS Code is now configured and will prompt for your token the first time you use agent mode. | ||
| ### Usage with Claude Desktop | ||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "docker", | ||
| "args": [ | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "ghcr.io/github/github-mcp-server:main" | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| ###Build from source | ||
| If you don't have Docker, you can use `go` to build the binary in the | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. this makes it sounds like docker is preferred over building from source. is that the case? | ||
| `cmd/github-mcp-server` directory, and use the `github-mcp-server stdio` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. this is hard to parse and will be harder for people who aren't used to building go projects | ||
| command with the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable set to | ||
| your token. | ||
| ## GitHub Enterprise Server | ||
| The flag `--gh-host` and the environment variable `GH_HOST` can be used to set | ||
| the GitHub Enterprise Server hostname. | ||
| ## i18n / Overriding Descriptions | ||
| The descriptions of the tools can be overridden by creating a | ||
| `github-mcp-server-config.json` file in the same directory as the binary. | ||
| The file should contain a JSON object with the tool names as keys and the new | ||
| descriptions as values. For example: | ||
| ```json | ||
| { | ||
| "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description", | ||
| "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository" | ||
| } | ||
| ``` | ||
| You can create an export of the current translations by running the binary with | ||
| the `--export-translations` flag. | ||
| 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. | ||
| ```sh | ||
| ./github-mcp-server --export-translations | ||
| cat github-mcp-server-config.json | ||
| ``` | ||
| You can also use ENV vars to override the descriptions. The environment | ||
| variable names are the same as the keys in the JSON file, prefixed with | ||
| `GITHUB_MCP_` and all uppercase. | ||
| For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can | ||
| set the following environment variable: | ||
| ```sh | ||
| export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description" | ||
| ``` | ||
| ## Tools | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. suggest breaking this out into a different file which we link to here. ideally one that is dynamically generated so this doesn't have to be kept up to date manually | ||
| ### Users | ||
| @@ -355,7 +338,7 @@ The flag `--gh-host` and the environment variable `GH_HOST` can be used to set t | ||
| ### Repository Content | ||
| - **Get Repository Content** | ||
| Retrieves the content of a repository at a specific path. | ||
| - **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 | ||
| - `repo`: Repository name (string, required) | ||
| - `path`: File or directory path (string, optional) | ||
| - **Get Repository Content for a Specific Branch** | ||
| Retrieves the content of a repository at a specific path for a given branch. | ||
| - **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 | ||
| - `branch`: Branch name (string, required) | ||
| - `path`: File or directory path (string, optional) | ||
| - **Get Repository Content for a Specific Commit** | ||
| Retrieves the content of a repository at a specific path for a given commit. | ||
| - **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 | ||
| - `sha`: Commit SHA (string, required) | ||
| - `path`: File or directory path (string, optional) | ||
| - **Get Repository Content for a Specific Tag** | ||
| Retrieves the content of a repository at a specific path for a given tag. | ||
| - **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 | ||
| - `tag`: Tag name (string, required) | ||
| - `path`: File or directory path (string, optional) | ||
| - **Get Repository Content for a Specific Pull Request** | ||
| Retrieves the content of a repository at a specific path for a given pull request. | ||
| - **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 | ||
| - `repo`: Repository name (string, required) | ||
| - `pr_number`: Pull request number (string, required) | ||
| - `path`: File or directory path (string, optional) | ||
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.