Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub MCP (Model Context Protocol) Server provides a standardized interface for AI agents to interact with GitHub resources. Installation and setup involve configuring the Go development environment, setting up authentication via personal access tokens, and choosing a deployment method between local binary execution or Docker containers.
The system is designed to communicate via the standard input/output (stdio) transport layer using JSON-RPC messages. Proper setup ensures that the server can securely access repository data, issues, and pull requests while maintaining the constraints defined by the user’s GitHub permissions.
Prerequisites
Before installing the server, ensure your local environment meets the following requirements:
- Go Language: Version 1.21 or later is required for building from source and running tests.
- Docker: Optional, but recommended for containerized execution.
- Linter:
golangci-lintv2 for local development. - GitHub Token: A
GITHUB_PERSONAL_ACCESS_TOKENis mandatory for the server to authenticate with GitHub APIs.
Sources: CONTRIBUTING.md:15-18, cmd/mcpcurl/README.md:15-18, cmd/github-mcp-server/main.go:34-37
Installation Methods
There are three primary ways to install and run the GitHub MCP server components.
Build from Source
To build the server components locally, navigate to the respective directory and use the Go toolchain:
# Building the main server
cd cmd/github-mcp-server
go build -o github-mcp-server
# Building the mcpcurl utility
cd cmd/mcpcurl
go build -o mcpcurl
Sources: cmd/mcpcurl/README.md:21-23
Go Install
You can install the utilities directly to your $GOPATH/bin:
go install github.com/github/github-mcp-server/cmd/mcpcurl@latest
Sources: cmd/mcpcurl/README.md:26-28
Docker Deployment
The project includes a Docker-based workflow, which is used extensively in end-to-end testing.
# Build the image
docker build -t github/github-mcp-server .
# Run the image
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN mcp/github
Sources: e2e/e2e_test.go:61-70, cmd/mcpcurl/README.md:46
Configuration
The server is configured primarily through environment variables and command-line flags. The project uses viper and cobra to manage these settings.
Global Flags and Environment Variables
The following table summarizes the core configuration options available for the server:
| Flag | Environment Variable | Type | Description |
|---|---|---|---|
--toolsets | GITHUB_TOOLSETS | String Slice | Comma-separated list of tool groups to enable (e.g., repos,issues). |
--gh-host | GITHUB_HOST | String | Specify GitHub hostname (e.g., for GitHub Enterprise). |
--read-only | GITHUB_READ_ONLY | Boolean | Restricts the server to read-only operations. |
--log-file | GITHUB_LOG_FILE | String | Path to the log file for command logging. |
--content-window-size | GITHUB_CONTENT_WINDOW_SIZE | Integer | Specifies the content window size (Default: 5000). |
Sources: cmd/github-mcp-server/main.go:72-82, e2e/e2e_test.go:102-115
Setting up the Environment
The following diagram illustrates how the server initializes its configuration from various sources during startup.
The server specifically expects a GITHUB_PERSONAL_ACCESS_TOKEN to be present in the environment or configuration.
Sources: cmd/github-mcp-server/main.go:34-37, cmd/github-mcp-server/main.go:101-106
Testing the Setup
After installation, verify the setup by running the automated test suite or using the mcpcurl diagnostic tool.
Local Test Execution
Run the full test suite to ensure all dependencies are correctly configured:
# Run all tests
go test -v ./...
# Run tests while updating snapshots
UPDATE_TOOLSNAPS=true go test ./...
Sources: CONTRIBUTING.md:32-37
Connectivity Verification with mcpcurl
mcpcurl acts as a client to verify that the MCP server is responding correctly via stdio.
This tool dynamically builds its CLI commands based on the schema retrieved from the server, allowing you to test specific GitHub tools like get_issue or list_repositories immediately.
Sources: cmd/mcpcurl/README.md:12-23, cmd/mcpcurl/README.md:113-118
Automated Documentation Generation
The project includes a utility for keeping documentation in sync with the actual tool schemas. If you modify the server tools, you should run the documentation generator as part of your setup.
# Execute doc generation
go run cmd/github-mcp-server/*.go generate-docs
This command updates README.md and docs/remote-server.md by mocking a GitHub client and extracting metadata from the toolset groups.
Sources: cmd/github-mcp-server/generate_docs.go:21-25, cmd/github-mcp-server/generate_docs.go:53-60
Conclusion
Setting up the GitHub MCP Server requires a valid GitHub Personal Access Token and a Go environment. By leveraging the provided Docker images or building local binaries, developers can quickly establish a standardized bridge between AI agents and GitHub's API. The inclusion of the mcpcurl tool further simplifies the verification of the installation by providing a dynamic interface to the server's capabilities.