GitHub MCP Server Environment Variables: Complete Configuration Guide

The GitHub MCP Server reads its configuration from environment variables prefixed with GITHUB_, including mandatory authentication tokens, toolset selection, security modes, and runtime settings.

The github/github-mcp-server repository uses environment variables as the primary mechanism for controlling MCP server behavior and configuration. These variables are automatically bound to Viper flags with the github prefix applied, allowing you to customize authentication, enable specific toolsets, enforce security policies, and configure logging without modifying code.

Core Configuration Variables

Authentication

The GITHUB_PERSONAL_ACCESS_TOKEN environment variable is mandatory. The server aborts startup if this variable is missing, as verified in cmd/github-mcp-server/main.go. This token is used for all GitHub API calls.

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_ABC123...

Tool Selection

Control which capabilities are exposed through the MCP server using these variables:

• GITHUB_TOOLSETS: Comma-separated list of toolsets to enable (e.g., issues,repo).
• GITHUB_TOOLS: Comma-separated list of individual tools to enable (e.g., get_me,get_file_contents).

Feature Flags

Enable specific server behaviors with these boolean or string flags:

• GITHUB_FEATURES: Enables named feature flags (e.g., scope-challenge).
• GITHUB_DYNAMIC_TOOLSETS: When set to true, toolsets are discovered at runtime instead of using the static default list.

Security and Access Control

Read-Only Mode

Set GITHUB_READ_ONLY to true to disable every non-read-only tool, regardless of other settings. This is useful for deployments where you want to guarantee no write operations occur.

Lockdown Mode

The GITHUB_LOCKDOWN_MODE environment variable disables all tools unless explicitly allowed by the --allow-tool flag. This is used for highly-restricted deployments where tools must be explicitly whitelisted.

Insiders Mode

Set GITHUB_INSIDERS to true to enable experimental or insiders-only tools and behavior that are not yet generally available.

Runtime and Debugging

Logging Configuration

Control server logging behavior with these variables:

• GITHUB_LOG_FILE: Path to a file where command request/response logs are written when command logging is enabled.
• GITHUB_ENABLE_COMMAND_LOGGING: Enables the command-logging feature (default false).
• GITHUB_EXPORT_TRANSLATIONS: When true, the server writes the translation map to github-mcp-server-config.json.

Profiling

Enable internal profiling by setting GITHUB_MCP_PROFILING_ENABLED to true. This is read by internal/profiler/profiler.go and helps diagnose performance issues.

Translation Overrides

Any environment variable prefixed with GITHUB_MCP_ overrides a translation key, as implemented in pkg/translations/translations.go. For example:

export GITHUB_MCP_UI_TITLE="My Custom GitHub MCP"

Implementation Details

The server uses Viper for configuration management in cmd/github-mcp-server/main.go. The binding code looks like this:

viper.SetEnvPrefix("github")          // → GITHUB_*
viper.AutomaticEnv()
_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
// … (same for every flag)

Additionally, the runtime configuration JSON schema in server.json declares the personal access token as a runtime argument:

{
  "runtimeArguments": [
    {
      "type": "named",
      "name": "-e",
      "description": "Set an environment variable in the runtime",
      "value": "GITHUB_PERSONAL_ACCESS_TOKEN={token}",
      "variables": {
        "token": { "isRequired": true, "isSecret": true, "format": "string" }
      }
    }
  ]
}

Practical Configuration Examples

Start a local stdio server with a personal access token and a custom toolset:

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_ABC123...
export GITHUB_TOOLSETS=issues,repos
export GITHUB_READ_ONLY=true     # optional, makes the server read-only

go run ./cmd/github-mcp-server stdio

Run the HTTP server on a non-default port with insiders mode enabled:

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_ABC123...
export GITHUB_PORT=9090
export GITHUB_INSIDERS=true
go run ./cmd/github-mcp-server http

Enable profiling and export translation data:

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_ABC123...
export GITHUB_MCP_PROFILING_ENABLED=true
export GITHUB_EXPORT_TRANSLATIONS=true
go run ./cmd/github-mcp-server stdio

Summary

• Authentication: GITHUB_PERSONAL_ACCESS_TOKEN is mandatory and must be set for the server to start.
• Tool Control: Use GITHUB_TOOLSETS, GITHUB_TOOLS, and GITHUB_DYNAMIC_TOOLSETS to customize available capabilities.
• Security: GITHUB_READ_ONLY, GITHUB_LOCKDOWN_MODE, and GITHUB_INSIDERS provide granular access control.
• Runtime: GITHUB_LOG_FILE, GITHUB_MCP_PROFILING_ENABLED, and GITHUB_MCP_<KEY> support debugging and customization.
• Implementation: All variables are bound via Viper in cmd/github-mcp-server/main.go with the GITHUB_ prefix.

Frequently Asked Questions

What happens if I don't set GITHUB_PERSONAL_ACCESS_TOKEN?

The server aborts startup immediately. According to the source code in cmd/github-mcp-server/main.go, this token is mandatory for all GitHub API operations, and the server will not initialize without it.

How do I enable only specific tools rather than entire toolsets?

Use the GITHUB_TOOLS environment variable with a comma-separated list of tool names (e.g., get_me,get_file_contents). This provides finer granularity than GITHUB_TOOLSETS, which enables groups of related tools.

Can I run the server in a completely read-only mode?

Yes. Set GITHUB_READ_ONLY to true. This overrides all other configuration and disables any tool that performs write operations, ensuring the server cannot modify any GitHub resources regardless of other settings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}