# GitHub MCP Server Environment Variables: Complete Configuration Guide

> Configure your GitHub MCP Server effortlessly using GITHUB_ environment variables. Learn about authentication, tool selection, security modes, and runtime settings in this comprehensive guide.

- Repository: [GitHub/github-mcp-server](https://github.com/github/github-mcp-server)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/github/github-mcp-server/blob/main/cmd/github-mcp-server/main.go). This token is used for all GitHub API calls.

```bash
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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/pkg/translations/translations.go). For example:

```bash
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`](https://github.com/github/github-mcp-server/blob/main/cmd/github-mcp-server/main.go). The binding code looks like this:

```go
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`](https://github.com/github/github-mcp-server/blob/main/server.json) declares the personal access token as a runtime argument:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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.