Add OAuth scopes customization via CLI flag and environment variable

- Add --oauth-scopes CLI flag to allow users to limit requested scopes
- Add GITHUB_OAUTH_SCOPES environment variable support
- Update OAuth authentication documentation with scopes customization guide
- Add examples for minimal, read-only, and custom scope configurations
- Update OAuth client ID comment to indicate it's a testing app (TODO for production)

Co-authored-by: SamMorrowDrums <[email protected]>

Author: Copilot

cmd/github-mcp-server/main.go

@@ -65,6 +65,14 @@ var (
 				}
 			}
 
+			// Parse OAuth scopes (similar to toolsets)
+			var oauthScopes []string
+			if viper.IsSet("oauth-scopes") {
+				if err := viper.UnmarshalKey("oauth-scopes", &oauthScopes); err != nil {
+					return fmt.Errorf("failed to unmarshal oauth-scopes: %w", err)
+				}
+			}
+
 			ttl := viper.GetDuration("repo-access-cache-ttl")
 			stdioServerConfig := ghmcp.StdioServerConfig{
 				Version:              version,
@@ -83,6 +91,7 @@ var (
 				RepoAccessCacheTTL:   &ttl,
 				OAuthClientID:        viper.GetString("oauth-client-id"),
 				OAuthClientSecret:    viper.GetString("oauth-client-secret"),
+				OAuthScopes:          oauthScopes,
 			}
 			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
@@ -110,6 +119,7 @@ func init() {
 	rootCmd.PersistentFlags().Duration("repo-access-cache-ttl", 5*time.Minute, "Override the repo access cache TTL (e.g. 1m, 0s to disable)")
 	rootCmd.PersistentFlags().String("oauth-client-id", "", "OAuth App client ID for device flow authentication (optional, uses default if not provided)")
 	rootCmd.PersistentFlags().String("oauth-client-secret", "", "OAuth App client secret for device flow authentication (optional, for confidential clients)")
+	rootCmd.PersistentFlags().StringSlice("oauth-scopes", nil, "Comma-separated list of OAuth scopes to request during device flow authentication (optional, uses default if not provided)")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -126,6 +136,7 @@ func init() {
 	_ = viper.BindPFlag("repo-access-cache-ttl", rootCmd.PersistentFlags().Lookup("repo-access-cache-ttl"))
 	_ = viper.BindPFlag("oauth-client-id", rootCmd.PersistentFlags().Lookup("oauth-client-id"))
 	_ = viper.BindPFlag("oauth-client-secret", rootCmd.PersistentFlags().Lookup("oauth-client-secret"))
+	_ = viper.BindPFlag("oauth-scopes", rootCmd.PersistentFlags().Lookup("oauth-scopes"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)

docs/oauth-authentication.md

@@ -242,6 +242,7 @@ The GitHub MCP Server provides the following CLI flags for OAuth configuration:
 |------|-------------|---------|---------|
 | `--oauth-client-id` | OAuth App client ID for device flow authentication | Default GitHub MCP OAuth App | `--oauth-client-id Ov23liYourClientID` |
 | `--oauth-client-secret` | OAuth App client secret (optional, for confidential clients) | None | `--oauth-client-secret your_client_secret` |
+| `--oauth-scopes` | Comma-separated list of OAuth scopes to request | Default scopes (see below) | `--oauth-scopes repo,read:org,gist` |
 | `--gh-host` | GitHub hostname for API requests and OAuth endpoints | `github.com` | `--gh-host https://github.yourcompany.com` |
 
 ### Usage Examples
@@ -256,6 +257,11 @@ github-mcp-server stdio
 github-mcp-server stdio --oauth-client-id Ov23liYourClientID
 ```
 
+**Limiting scopes (minimal permissions):**
+```bash
+github-mcp-server stdio --oauth-scopes repo,read:org,gist
+```
+
 **GHES with custom OAuth App:**
 ```bash
 github-mcp-server stdio --gh-host https://github.yourcompany.com --oauth-client-id Ov23liGHESClientID
@@ -266,6 +272,11 @@ github-mcp-server stdio --gh-host https://github.yourcompany.com --oauth-client-
 github-mcp-server stdio --oauth-client-id Ov23liYourClientID --oauth-client-secret your_secret
 ```
 
+**Custom scopes with custom OAuth App:**
+```bash
+github-mcp-server stdio --oauth-client-id Ov23liYourClientID --oauth-scopes repo,read:org,user:email
+```
+
 ## Environment Variables
 
 All CLI flags can also be configured via environment variables with the `GITHUB_` prefix:
@@ -274,6 +285,7 @@ All CLI flags can also be configured via environment variables with the `GITHUB_
 |---------------------|---------------------|---------|
 | `GITHUB_OAUTH_CLIENT_ID` | `--oauth-client-id` | `export GITHUB_OAUTH_CLIENT_ID=Ov23liYourClientID` |
 | `GITHUB_OAUTH_CLIENT_SECRET` | `--oauth-client-secret` | `export GITHUB_OAUTH_CLIENT_SECRET=your_secret` |
+| `GITHUB_OAUTH_SCOPES` | `--oauth-scopes` | `export GITHUB_OAUTH_SCOPES=repo,read:org,gist` |
 | `GITHUB_HOST` | `--gh-host` | `export GITHUB_HOST=https://github.yourcompany.com` |
 | `GITHUB_PERSONAL_ACCESS_TOKEN` | N/A (disables OAuth) | `export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_token` |
 
@@ -309,11 +321,63 @@ These scopes form a superset of the `gh` CLI minimal scopes (`repo`, `read:org`,
 
 ### Customizing Scopes
 
-Currently, scopes are not customizable via CLI flags or environment variables. They are defined in the source code (`pkg/github/auth.go`) as `DefaultOAuthScopes`. To customize scopes, you would need to:
+You can customize the requested scopes using the `--oauth-scopes` CLI flag or `GITHUB_OAUTH_SCOPES` environment variable:
+
+**CLI Flag:**
+```bash
+github-mcp-server stdio --oauth-scopes repo,read:org,gist
+```
+
+**Environment Variable:**
+```bash
+export GITHUB_OAUTH_SCOPES=repo,read:org,user:email
+github-mcp-server stdio
+```
 
-1. Fork the repository
-2. Modify the `DefaultOAuthScopes` variable
-3. Build your custom version
+**Docker with environment variable:**
+```json
+{
+  "github": {
+    "command": "docker",
+    "args": ["run", "-i", "--rm", "-e", "GITHUB_OAUTH_SCOPES", "ghcr.io/github/github-mcp-server"],
+    "env": {
+      "GITHUB_OAUTH_SCOPES": "repo,read:org,gist"
+    }
+  }
+}
+```
+
+#### Minimal Recommended Scopes
+
+For basic functionality, you can use a minimal set of scopes:
+
+```bash
+--oauth-scopes repo,read:org,gist
+```
+
+This provides:
+- `repo`: Access to repositories, issues, and PRs
+- `read:org`: Read organization and team information
+- `gist`: Manage gists
+
+**Note**: Some MCP tools may not function properly with reduced scopes. Review the scopes table above to understand which scopes are required for specific functionality.
+
+#### Common Scope Combinations
+
+**Read-only operations:**
+```bash
+--oauth-scopes repo,read:org,read:user
+```
+
+**Full repository access with notifications:**
+```bash
+--oauth-scopes repo,read:org,notifications,user:email
+```
+
+**Enterprise with minimal scopes:**
+```bash
+--oauth-scopes repo,read:org,read:gpg_key
+```
 
 ## Security Considerations
 

internal/ghmcp/server.go

@@ -74,6 +74,10 @@ type MCPServerConfig struct {
 
 	// OAuthClientSecret is the OAuth App client secret (optional, for confidential clients).
 	OAuthClientSecret string
+
+	// OAuthScopes is a list of OAuth scopes to request during device flow authentication.
+	// If empty, the default scopes defined in DefaultOAuthScopes are used.
+	OAuthScopes []string
 }
 
 // githubClients holds all the GitHub API clients created for a server instance.
@@ -287,7 +291,7 @@ func NewUnauthenticatedMCPServer(cfg MCPServerConfig) (*UnauthenticatedServerRes
 	oauthHost := github.NewOAuthHostFromAPIHost(cfg.Host)
 
 	// Create auth manager
-	authManager := github.NewAuthManager(oauthHost, cfg.OAuthClientID, cfg.OAuthClientSecret, nil)
+	authManager := github.NewAuthManager(oauthHost, cfg.OAuthClientID, cfg.OAuthClientSecret, cfg.OAuthScopes)
 
 	// Create the MCP server with capabilities advertised for dynamic tool registration
 	serverOpts := &mcp.ServerOptions{
@@ -456,6 +460,10 @@ type StdioServerConfig struct {
 
 	// OAuthClientSecret is the OAuth App client secret (optional, for confidential clients).
 	OAuthClientSecret string
+
+	// OAuthScopes is a list of OAuth scopes to request during device flow authentication.
+	// If empty, the default scopes defined in DefaultOAuthScopes are used.
+	OAuthScopes []string
 }
 
 // RunStdioServer is not concurrent safe.
@@ -494,6 +502,7 @@ func RunStdioServer(cfg StdioServerConfig) error {
 			Logger:            logger,
 			OAuthClientID:     cfg.OAuthClientID,
 			OAuthClientSecret: cfg.OAuthClientSecret,
+			OAuthScopes:       cfg.OAuthScopes,
 			// Pass config for use after authentication
 			EnabledToolsets:   cfg.EnabledToolsets,
 			EnabledTools:      cfg.EnabledTools,

pkg/github/auth.go

@@ -111,7 +111,8 @@ func NewOAuthHostFromAPIHost(hostname string) OAuthHost {
 }
 
 // DefaultOAuthClientID is the OAuth App client ID for the GitHub MCP Server.
-// This OAuth App is registered and managed by GitHub for use with this server.
+// TODO: This is currently a testing OAuth App. An official GitHub-managed OAuth App
+// will be registered before production release.
 // The client ID is safe to embed in source code per OAuth 2.0 spec for public clients.
 // Users can override this with --oauth-client-id for enterprise scenarios.
 const DefaultOAuthClientID = "Ov23ctTMsnT9LTRdBYYM"