diff --git a/.gitignore b/.gitignore index 485dee64..b753d0e8 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 1d7eba36..acea0dee 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.