Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1699,6 +1699,35 @@ docker run -i --rm \
ghcr.io/github/github-mcp-server
```

## Allowed Repositories

When running locally (stdio), you can restrict the server to a fixed set of repositories with `--allowed-repos` or the `GITHUB_ALLOWED_REPOS` environment variable. This is useful when a token can see more than an agent should, for example a fine-grained token, which can always read public repositories.

Each entry is `owner/repo`, or `owner/*` for every repository of an owner. The repository part also accepts wildcards such as `octo-org/svc-*`. Names are matched case-insensitively.

```bash
./github-mcp-server stdio --allowed-repos=octo-org/*,octocat/hello-world
```

```bash
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_ALLOWED_REPOS=octo-org/*,octocat/hello-world \
ghcr.io/github/github-mcp-server
```

When an allowlist is set, every tool call, `repo://` resource read and resource completion is checked before any GitHub API request is made. The check fails closed: a call goes through only when every repository it can reach is known from its arguments and is in the list.

- Calls with `owner` and `repo` must name an allowed repository. Secondary repositories named by other arguments (`parent_owner`/`parent_repo` on issue creation, `related_owner`/`related_repo` on issue dependencies, `item_owner`/`item_repo` on project items) are checked the same way.
- Calls scoped to a whole owner or organization (for example project tools or organization security advisories) need an `owner/*` entry. `list_notifications` and `mark_all_notifications_read` need both `owner` and `repo`, because without them they cover every repository.
- `create_repository` and `fork_repository` need an `organization` with an `owner/*` entry; the personal account cannot be checked.
- Rulesets and custom properties are checked at the selected `level`: `repository` needs `owner` and `repo`, `organization` needs `org` with an `org/*` entry, and `enterprise` is rejected.
- Search tools need a positive `repo:`, `org:` or `user:` qualifier in the query, and every such qualifier must be allowed. Negated qualifiers such as `-repo:` only narrow the results and are ignored; quoted qualifiers are free text and don't count as scope. Queries with `OR`, `NOT`, `AND` or parentheses are rejected, because a qualifier in one branch doesn't constrain the others. `search_issues` and `search_pull_requests` also accept `owner` and `repo` arguments, as long as the query has no `repo:` qualifier of its own.
- Tools that can't be tied to a repository are rejected: notification threads addressed by ID, project items (`list_project_items`, `get_project_item`, and item updates or deletions that don't name `item_owner`, `item_repo` and `issue_number`), and project views or status updates addressed by node ID. Tools that never return repository content (`get_me`, `get_teams`, `get_team_members`, `search_users`, `search_orgs`, global security advisories and gists) keep working, and so do the bundled `ui://` app resources.
- Resource completions for `repo://` templates are checked against the resolved `owner` and `repo`; owner suggestions, and repository suggestions for an owner without an `owner/*` entry, are rejected.

Rejected calls return a tool error that names the repository and the allowlist, so the model can correct itself. The allowlist limits what this server will do; it doesn't change what the token itself can access.

## Lockdown Mode

Lockdown mode limits the content that the server will surface from public repositories. When enabled, the server checks whether the author of each item has push access to the repository. Private repositories are unaffected, and collaborators keep full access to their own content.
Expand Down
10 changes: 10 additions & 0 deletions cmd/github-mcp-server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,13 @@ var (
}
}

var allowedRepos []string
if viper.IsSet("allowed_repos") {
if err := viper.UnmarshalKey("allowed_repos", &allowedRepos); err != nil {
return fmt.Errorf("failed to unmarshal allowed-repos: %w", err)
}
}

ttl := viper.GetDuration("repo-access-cache-ttl")
stdioServerConfig := ghmcp.StdioServerConfig{
Version: serverVersion,
Expand All @@ -132,6 +139,7 @@ var (
InsidersMode: viper.GetBool("insiders"),
ExcludeTools: excludeTools,
RepoAccessCacheTTL: &ttl,
AllowedRepos: allowedRepos,
}

// When no static token is provided, log in via OAuth using the given
Expand Down Expand Up @@ -260,6 +268,7 @@ func init() {
stdioCmd.Flags().String("oauth-client-id", "", "OAuth App or GitHub App client ID, enabling interactive OAuth login when no token is set")
stdioCmd.Flags().String("oauth-client-secret", "", "OAuth client secret, if the app requires one (it is a public, non-confidential credential for distributed clients)")
stdioCmd.Flags().StringSlice("oauth-scopes", nil, "Comma-separated OAuth scopes to request; also filters tools to those scopes. Defaults to the full supported set")
stdioCmd.Flags().StringSlice("allowed-repos", nil, "Comma-separated repositories (owner/repo or owner/*) that tools may access; calls outside the list are rejected")
stdioCmd.Flags().Int("oauth-callback-port", 0, "Fixed local port for the OAuth callback server. Defaults to a random port; set a fixed port when mapping it through Docker")

// The private key has no flag because passing it in argv would expose it.
Expand Down Expand Up @@ -293,6 +302,7 @@ func init() {
_ = viper.BindPFlag("oauth-client-id", stdioCmd.Flags().Lookup("oauth-client-id"))
_ = viper.BindPFlag("oauth-client-secret", stdioCmd.Flags().Lookup("oauth-client-secret"))
_ = viper.BindPFlag("oauth-scopes", stdioCmd.Flags().Lookup("oauth-scopes"))
_ = viper.BindPFlag("allowed_repos", stdioCmd.Flags().Lookup("allowed-repos"))
_ = viper.BindPFlag("oauth-callback-port", stdioCmd.Flags().Lookup("oauth-callback-port"))
_ = viper.BindPFlag("app-id", stdioCmd.Flags().Lookup("app-id"))
_ = viper.BindPFlag("app-installation-id", stdioCmd.Flags().Lookup("app-installation-id"))
Expand Down
25 changes: 25 additions & 0 deletions docs/server-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ We currently support the following ways in which the GitHub MCP Server can be co
| Exclude Tools | `X-MCP-Exclude-Tools` header | `--exclude-tools` flag or `GITHUB_EXCLUDE_TOOLS` env var |
| Read-Only Mode | `X-MCP-Readonly` header or `/readonly` URL | `--read-only` flag or `GITHUB_READ_ONLY` env var |
| Lockdown Mode | `X-MCP-Lockdown` header | `--lockdown-mode` flag or `GITHUB_LOCKDOWN_MODE` env var |
| Allowed Repositories | Not available | `--allowed-repos` flag or `GITHUB_ALLOWED_REPOS` env var |
| Insiders Mode | `X-MCP-Insiders` header or `/insiders` URL | `--insiders` flag or `GITHUB_INSIDERS` env var |
| Feature Flags | `X-MCP-Features` header or `?features=` URL query parameter | `--features` flag |
| Scope Filtering | Always enabled | Always enabled |
Expand Down Expand Up @@ -341,6 +342,30 @@ As an intentional exception, content authored by trusted bot accounts (currently

---

### Allowed Repositories

**Best for:** Sandboxing an agent to specific repositories when the token can see more, for example a fine-grained token that also has read access to public repositories.

Pass `owner/repo` or `owner/*` entries. Tool calls, `repo://` resource reads and resource completions outside the list are rejected before any GitHub API request is made, search queries must be scoped with positive `repo:`, `org:` or `user:` qualifiers inside the list, and tools whose target cannot be told from their arguments (notification threads, project items, enterprise-level settings) are rejected. See [Allowed Repositories](../README.md#allowed-repositories) for the full rules. This option is only available for the local server.

```json
{
"type": "stdio",
"command": "go",
"args": [
"run",
"./cmd/github-mcp-server",
"stdio",
"--allowed-repos=octo-org/*,octocat/hello-world"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
}
}
```

---

### Insiders Mode

**Best for:** Users who want early access to experimental features and new tools before they reach general availability.
Expand Down
Loading