From a4e05c9843c51df1bc36abfde8c45b4cead5704a Mon Sep 17 00:00:00 2001 From: Toby Padilla Date: Fri, 28 Mar 2025 13:02:15 -0600 Subject: [PATCH] docs: update README --- .gitignore | 1 + README.md | 235 +++++++++++++++++------------------------------------ 2 files changed, 75 insertions(+), 161 deletions(-) diff --git a/.gitignore b/.gitignore index 485dee64b..b753d0e8c 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .idea +cmd/github-mcp-server/github-mcp-server diff --git a/README.md b/README.md index 1d7eba365..acea0dee8 100644 --- a/README.md +++ b/README.md @@ -1,130 +1,113 @@ # GitHub MCP Server -GitHub MCP Server implemented in Go. +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. -## Setup +## Use Cases -Create a GitHub Personal Access Token with the appropriate permissions -and set it as the GITHUB_PERSONAL_ACCESS_TOKEN environment variable. +- Automating GitHub workflows and processes. +- Extracting and analyzing data from GitHub repositories. +- Building AI powered tools and applications that interact with GitHub's ecosystem. -## Testing in VS Code Insiders +## Prerequisites -### Requirements +[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. -You can either use a Docker image or build the binary from the repo. +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). -#### Docker image +To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed. -As of now, this repo is private, and hence the docker image is not available publicly. To pull it, -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) -for more details. +## Installation -To make sure you can access the GitHub docker registry, run the following command: +### Usage with VS Code -```bash -docker pull ghcr.io/github/github-mcp-server:main -``` +Install the GitHub MCP server into VS Code by clicking here: -If the above command works, you are good to go. +[Install in VS Code Insiders](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) -#### Build from repo -First, install `github-mcp-server` by cloning the repo and running the following command: +Or run this command in your terminal: ```bash -go install ./cmd/github-mcp-server -``` +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}]}' -If you don't want to clone the repo, you can run: - -```bash -GOPRIVATE=github.com/github go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest ``` +VS Code is now configured and will prompt for your token the first time you use agent mode. -This will install the `github-mcp-server` binary in your `$GOPATH/bin` directory. +### Usage with Claude Desktop -Find where the binary is installed by running: - -```bash -# note this assumes $GOPATH/bin is in your $PATH -which github-mcp-server +```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": "" + } + } + } +} ``` -### Start VS Code Insiders +### Build from source -Start VS Code Insiders and make sure you pass the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to the process. +If you don't have Docker, you can use `go` to build the binary in the +`cmd/github-mcp-server` directory, and use the `github-mcp-server stdio` +command with the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable set to +your token. -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 -start it with the following command: +## GitHub Enterprise Server -```bash -export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here -code-insiders -``` +The flag `--gh-host` and the environment variable `GH_HOST` can be used to set +the GitHub Enterprise Server hostname. -Another way is to set the environment variable in your shell configuration file (e.g., `.bashrc`, `.zshrc`, etc.). +## i18n / Overriding Descriptions -Create a new file `.vscode/mcp.json` and provide this configuration: +The descriptions of the tools can be overridden by creating a +`github-mcp-server-config.json` file in the same directory as the binary. -If you are using the docker image, use this configuration: +The file should contain a JSON object with the tool names as keys and the new +descriptions as values. For example: ```json { - "inputs": [ - { - "id": "github-pat", - "type": "promptString", - "description": "Github Personal Access Token", - "password": true, - } - ], - "servers": { - "github-mcp-server": { - "type": "stdio", - "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}" - } - } - } + "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description", + "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository" } ``` -When you start the server, VS Code will prompt for your token, as indicated by `${input:github-pat}`. +You can create an export of the current translations by running the binary with +the `--export-translations` flag. -If you built the binary from the repo use this configuration: +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. -```json -{ - "mcp": { - "inputs": [ ], - "servers": { - "mcp-github-server": { - "command": "path-to-your/github-mcp-server", - "args": ["stdio"], - "env": { } - } - } - } -} +```sh +./github-mcp-server --export-translations +cat github-mcp-server-config.json ``` -Right on top of `servers`, you should see a `Start` link to start the server. +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: -Try something like the following prompt to verify that it works: - -``` -I'd like to know more about my GitHub profile. +```sh +export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description" ``` -## GitHub Enterprise Server - -The flag `--gh-host` and the environment variable `GH_HOST` can be used to set the GitHub Enterprise Server hostname. - - ## Tools ### 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** +- **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** +- **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** +- **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** +- **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** +- **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) - -## Standard input/output server - -```sh -go run cmd/github-mcp-server/main.go stdio -``` - -E.g: - -Set the PAT token in the environment variable and run: - -```sh -script/get-me -``` - -And you should see the output of the GitHub MCP server responding with the user information. - -```sh -GitHub MCP Server running on stdio -{ - "jsonrpc": "2.0", - "id": 3, - "result": { - "content": [ - { - "type": "text", - "text": "{\"login\":\"juruen\",\"id\" ... } - } - ] - } -} - -``` - -## i18n / Overriding descriptions - -The descriptions of the tools can be overridden by creating a github-mcp-server.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.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" -``` - -## TODO - -Testing - -- Integration tests -- Blackbox testing: ideally comparing output to Anthropic's server to make sure that this is a fully compatible drop-in replacement. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy