Configuration & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub MCP Server utilizes a hybrid configuration model leveraging command-line flags and environment variables to define its operational state. At its core, the system requires a GitHub Personal Access Token (PAT) to interact with the GitHub API, supporting both standard GitHub.com and GitHub Enterprise environments.
The configuration layer manages security constraints (such as read-only mode), performance tuning (content window sizes), and tool availability (toolset filtering). This ensures that the server can be deployed in diverse environments, from local developer machines using stdio to containerized infrastructures.
Authentication Mechanism
Authentication is primarily handled through a GitHub Personal Access Token. The server initializes a GitHub client that applies this token to all outgoing REST and GraphQL requests.
Supported Authentication Credentials
- Personal Access Token (PAT): Required for all operations. The server specifically looks for the
GITHUB_PERSONAL_ACCESS_TOKENenvironment variable or thepersonal-access-tokenconfiguration key. - Enterprise Support: Users can specify a custom GitHub hostname via the
gh-hostflag orGITHUB_HOSTenvironment variable to support GitHub Enterprise Cloud (GHEC) or GitHub Enterprise Server (GHES).
Sources: cmd/github-mcp-server/main.go:37-40, e2e/e2e_test.go:36-42, e2e/e2e_test.go:53-61
Authentication Flow
The following diagram illustrates how credentials move from the configuration layer into the GitHub API clients.
Sources: cmd/github-mcp-server/main.go:37-60
Configuration Management
The project uses cobra for CLI command handling and viper for configuration synchronization. Configuration keys are automatically prefixed with GITHUB_ when loaded from environment variables.
Global Configuration Options
| Flag | Env Variable | Type | Description |
|---|---|---|---|
--personal-access-token | GITHUB_PERSONAL_ACCESS_TOKEN | String | GitHub PAT for authentication |
--gh-host | GITHUB_HOST | String | Custom GitHub hostname (e.g., Enterprise) |
--read-only | GITHUB_READ_ONLY | Boolean | Restricts the server to non-mutating operations |
--toolsets | GITHUB_TOOLSETS | StringSlice | Comma-separated list of tool groups to enable |
--dynamic-toolsets | GITHUB_DYNAMIC_TOOLSETS | Boolean | Enables dynamic tool discovery |
--content-window-size | GITHUB_CONTENT_WINDOW_SIZE | Integer | Specifies the maximum size for content windows |
--log-file | GITHUB_LOG_FILE | String | Path to the server log file |
Sources: cmd/github-mcp-server/main.go:71-82, cmd/github-mcp-server/main.go:85-86
Toolset Filtering
The server allows granular control over which tools are exposed to the Model Context Protocol. By default, all tools are enabled, but the toolsets configuration allows restricting capabilities to specific modules like repos or issues.
Sources: cmd/github-mcp-server/main.go:46-50, e2e/e2e_test.go:185-188
Operational Modes
Read-Only Mode
When --read-only is enabled, the server restricts operations to those that do not modify state. In the codebase, this is often implemented via ReadOnlyHint annotations within tool definitions, signaling to the MCP client that these tools are safe for execution in restricted environments.
Sources: cmd/github-mcp-server/main.go:73, pkg/github/issues.go:181, pkg/github/repositories.go:21
Stdio Communication
The server primarily operates over stdio, using JSON-RPC messages. This allows it to be invoked easily via shell commands or within Docker containers.
Client Initialization in Tests
The end-to-end (E2E) testing suite mimics the production configuration environment. It ensures that the Docker container or in-process server is instantiated with the correct environment variables before executing tests.
// From e2e/e2e_test.go
args := []string{
"docker", "run", "-i", "--rm",
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
}
// Add toolsets environment variable to the Docker arguments
if len(opts.enabledToolsets) > 0 {
args = append(args, "-e", "GITHUB_TOOLSETS")
}
Sources: e2e/e2e_test.go:92-105
Conclusion
The GitHub MCP Server relies on a robust configuration architecture that prioritizes security and flexibility. By combining Viper's environment variable mapping with Cobra's flag system, it ensures that sensitive credentials like Personal Access Tokens are managed securely while allowing runtime behavior—such as toolset availability and read-only restrictions—to be tuned per deployment.