github-mcp-gateway

Удалённый MCP-сервер, который даёт любому MCP-клиенту аутентифицированный доступ к GitHub — репозиториям, issue, pull request, содержимому файлов и поиску — через настоящий OAuth 2.1 на Cloudflare Workers.

Работает с Claude Code, Claude.ai / Cowork и любым MCP-клиентом, соответствующим спецификации. Аутентификация — это user-to-server поток от GitHub App: сервер может достать только те репозитории, которые вы сами выбрали на экране установки GitHub, а не всё, что видно из вашего аккаунта.

Это исходный код, который вы запускаете, а не сервис, на который вы подписываетесь. Общего экземпляра нет. Вы разворачиваете собственный Worker под собственный GitHub App, и ваши учётные данные никогда не покидают ваш аккаунт — см. Ограничения дизайна (осознанные). Настройка — один скрипт и около десяти минут:

git clone https://github.com/mazze93/github-mcp-gateway
cd github-mcp-gateway && ./scripts/setup.sh <your-github-login>

Что вы получаете

Related MCP server: Cloudflare GitHub OAuth MCP Server

Зачем это существует и какова его форма

MCP-клиент не может общаться с GitHub API напрямую с вашими учётными данными — ему нужно что-то посередине, что (а) доказывает, кто спрашивает, (б) держит настоящий GitHub-токен, (в) превращает вызовы инструментов в GitHub API-запросы. Этот Worker и есть средний слой, и он играет две роли OAuth одновременно:

• OAuth-клиент для GitHub (выше по потоку) — он проводит вас через собственный консенсус GitHub и обменивает полученный код на токен.

• OAuth-сервер для MCP-клиента (ниже по потоку) — клиент никогда не видит ваш GitHub GitHub-токен. Он получает свой собственный токен от этого Worker, ограниченный только этим Worker. Собственная библиотека Cloudflare @cloudflare/workers-oauth-provider реализует этот нижний поток: OAuth 2.1, PKCE и Dynamic Client Registration (DCR) — именно DCR позволяет клиенту зарегистрировать себя при первом подключении без необходимости вручную создавать учётные данные для него.

MCP client ──OAuth (DCR, PKCE)──▶ this Worker ──OAuth (GitHub App)──▶ GitHub
                                       │
                                       ▼
                               Workers KV (OAUTH_KV)
                           state · refresh tokens · approved clients

Почему GitHub App вместо классического OAuth App

Собственный шаблон Cloudflare использует классическое OAuth App, что проще, но URL — all-or-nothing repo scope и токен, который никогда не истекает, если вы сами не запрограммируете истечение. Эта сборка использует GitHub App с user-to-server token flow вместо:

• Ограничение на уровне репозитория при установке — вы выбираете точно, какие репозитории этот сервер может трогать (собственная выборка установки GitHub), а не «всё, что видит этот аккаунт».

• Токены, которые реально истекают и сами обновляются — когда включён «Expire user authorization tokens», GitHub возвращает 8-часовой access-токен плюс 6-месячный refresh-токен, и использование refresh-токена чеканит новую пару. Пока вы пользуетесь этим сервером хотя бы раз в 6 месяцев, он никогда не устареет, и вам не придётся вручную чеканить новый токен.

Цикл обработки показан из-за обработки жизненный цикл токена, ниже.

1. Создайте GitHub App

Перейдите на github.com/settings/apps/new (личный аккаунт) или github.com/organizations/<org>/settings/apps/new (владение принадлежит org — используйте, если хотите его под org, а не под личным аккаунтом).

После создания:

1. Указывайте на Client ID в верхней части страницы настроек приложения.

2. Нажмите Generate a new client secret — скопируйте сейчас, он показывается только один раз.

3. В разделе Optional features найдите User-to-server token expiration и нажмите Opt-in. Это то, что вообще создаёт refresh-токены, — пропустите, и сервер упадёт на шаге callback с явной ошибкой, которая говорит вам вернуться и сделать это.

4. Перейдите в Install App (левый сайдбар) и установите в ваш аккаунт, выбрав Only select repositories — выберите репозитории, к которым этому серверу быть допущенным (позже можно добрать с того же экрана).

Вам понадобится второй GitHub App, настроенный идентично, но с callback URL http://localhost:8788/callback, если вы хотите итерировать локально с wrangler dev перед деплоем.

2. Создайте пространство имён KV

Самый быстрый путь — ./scripts/setup.sh <ваш-github-login> устанавливает зависимости, создаёт пространство имён и переписывает wrangler.jsonc с вашим space id и вашим login. Затем переходите к шагу 3.

Вручную:

cd github-mcp-gateway
npm ci
npx wrangler kv namespace create OAUTH_KV

Скопируйте возвращённый id в wrangler.jsonc под kv_namespaces[0].id, заменив закоммиченное значение. Это значение — живое пространство сопровождающего, а не плейсхолдер, — репозиторий является живым деплоем, а также шаблоном, поэтому проверенный конфиг является реальным. Это идентификатор, а не учётная запись: он не даёт форку ничего, но оставить его на месте означает, что ваш Worker запускается против пространства, которое ваш аккаунт не может достать.

3. Установите секреты и var allowlist

npx wrangler secret put GITHUB_APP_CLIENT_ID
npx wrangler secret put GITHUB_APP_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

ALLOWED_GITHUB_LOGINS — это var, а не секрет — добавьте его в wrangler.json под верхнеуровневый блок "vars":

GXP5 Это allowlist на усмотрение, проверяемый на этапе OAuth-коллбэка: даже если только вы можете пройти GitHub consent экран только для вашего собственного аккаунта это делает гейт кода код-эксплицитным, а не неявным на «кто может аутентифицироваться». Незаданное или пустое значение отрицает всех — он проваливается закрытым, поэтому пропущенный шаг блокирует вас, а не открывает сервер.

4. Деплой

npx wrangler deploy

5. Подключите клиент

Укажите любой MCP-клиент на:

https://github-mcp-gateway.<your-subdomain>.workers.dev/mcp

• Claude Code: claude mcp add --transport http github-mcp-gateway <url>

• Claude.ai / Cowork: добавьте свой MCP-коннектор с этим URL.

Клиент регистрирует себя через DCR, перенаправляет вас через этот сервер, затем GitHub, и возвращается с инструментами.

Локальная разработка

cp .dev.vars.example .dev.vars   # fill in the *local* GitHub App's credentials
npx wrangler dev

wrangler dev служит на http://localhost:8788 — укажите MCP-клиент (например, MCP Inspector) на http://localhost:8788/mcp.

Жизненный цикл токена

Существует два независимых токен отношения, на разных тактовых частотах:

1. Cowork ↔ этот Worker. Стандартные OAuth 2.1 access/refresh-токены, выпущенные workers-oauth-provider. Иом обновляет их автоматически, по спецификации MCP — здесь нечего менеджерить.

2. Этот Worker ↔ GitHub. 8-часовой access-токен + 6-месячный refresh-токен. src/github-client.ts проверяет истечение срока действия перед каждым вызовом GitHub API и прозрачно обновляет, когда он становится в пределах 5 минут, сохраняя повернутую пару в OAUTH_KV под github:tokens:{ваш-логин}. Это намеренно не подключено к workers-oauth-provider's точке tokenExchangeCallback — у этого механизма есть открытый upstream-баг (пропсы, устаревающие после обновления, вызывали повторные циклы аутентификации; см. Ссылки) — поэтому вместо этого обрабатывается напрямую в слое инструментов, где это проще рассуждать и тестировать.

Если GitHub refresh-токен сам по себе истекает (не используется 6+ месяцев) или вы отзываете доступ приложения, следующий вызов инструмента падает с чётким сообщением ReauthorizationRequiredError, инструктируя вас отключиться и заново подключиться в Cowork. Здесь нет тихого режима отказа — он либо работает тихо в фоне вовремя, либо говорит вам точно, что делать.

Инструменты

Все инструменты списка принимают per_page и page для пагинации.

github_merge_pull_request и github_delete_file — две деструктивные операции: необратимые как только вызываются. Клиент должен подтвердить с вами перед вызовом.

github_update_repo (description, homepage, topics) требует, чтобы у GitHub App было разрешение репозитория Administration. В текущей конфигурации приложения (Contents/Issues/PRs/Metadata) его нет — добавьте разрешение в настройках приложения и полтавно заново согласие на установку, чтобы активировать инструмент, либо вносите такие изменения через CLI gh.

Проектные ограничения (осознанные)

Прочитайте это перед внедрением — это выбор, а не пробелы в качестве.

Один оператор на одно развёртывание

Этот сервер однотенантный по построению. ALLOWED_GITHUB_LOGINS ограничивает callback OAuth; и хотя переменная принимает список через запятую, а хранилище токенов уже разбито по логинам (github:tokens:{login}), целевая форма — одно развёртывание на человека.

Это следствие модели угроз. Общее развёртывание означало бы, что в KV-пространстве имён одного оператора лежат чужие refresh-токены GitHub — шестимесячные права с доступом на запись в репозитории. Это делает оператора хранителем учётных данных с обязательством уведомления об утечках, на инфраструктуре без таких гарантий. Самостоятельный хостинг оставляет каждую учётную запись в аккаунте, которому принадлежит аккаунт, — в этом весь смысл дизайна.

Итак: сделайте форк и запускайте собственный экземпляр. Именно для этого существует ./scripts/setup.sh. Настройка занимает примерно десять минут, а бесплатного тарифа Cloudflare достаточно для личного использования.

Область репозитория определяется при установке, а не этим сервером

По поскольку это GitHub App, и "классическое OAuth-приложение", доступность репозитории — те, которые вы выбирайте на экране установления GitHub. Этот сервер не может их расширить", и ни один вызов инструмента не может выйти за его пределы. Чтобы изменить область, измените установку.

github_update_repo требует разрешение, которое не входит в комплект приложения

Ему нужны разрешения репозитория Administration. Добавьте его в настройках приложения и повторно одобрите установку, либо используйте gh CLI для изменения описания и тем.

Это не размещённый сервис

Публичного экземпляра, на который можно указать клиенту, не существ. Любой URL workers.dev, который вы найдете в этом репозитории (в deploy.yml, SECURITY.md или в заголовке Dockerfile), — это собственный деплой мейнтейнера, и его список разрешённых вас отклонит. Это исходный код, который вы запускаете сами, и не сервис, под который вы регистрируетесь.

Заметки по безопасности и известные upstream-проблемы, учтённые в этой сборке

• CSRF, повторное использование state, фиксация сессии — обрабатывается в src/oauth/workers-oauth-utils.ts с помощью пары CSR-токен + cookie на форме подтверждения, одноразового KV-флаг, создаваемого в KV (время жизни 10 минут), и cookie сессии (SHA-256-хеш state-токена), подтверждающего, что браузер, завершающий callback GitHub, — это тот же, который начал процедуру.

• workers-oauth-provider Issue #133 — ошибка обработки пути при валидации аудитории в каких-то версиях вызывала ошибки именно для подключений Claude.ai и Cocoon. Эта сборка не добавляет компоненты пути в какой-либо индикатор ресурса (/mcp и /sse регистрируются в корне apiHandlers, а не вложенными в более длинный путь) — это докуменен. Если первая попытка подключения Cowork падает на этапе обмена токенами, сначала это очевидно всходе: смотрите upstream.

• Issue #108 (проверка аудитории RFC 8707 с путями) — та же первопричина, что и выше; то же обходное решение.

• Issue #29 (несовпадение redirect URI в проде) — есть сообщения, что для некоторых клиентов динамически зарегистрированные redirect URIs в проде ведут себя иначе, чем в wrangler dev. Если редирект Cowork не работает только после деплоя — а локально работает, искать следует именно это.

• Префикс cookie __Host- по всему проекту — гарантире имм (браузер enforced), что cookie может быть установлена только этим конкретным origin по HTTPS, без атрибута Domain, способного расширить область её действия.

Ссылки

• Cloudflare Agents — Build a Remote MCP Server

• cloudflare/workers-oauth-provider — использование низьоуровневой низкоуровневой реализации OAuth 2.1, от которой это зависит

• GitHub Docs — Refreshing user access tokens

• workers-oauth-provider Issue #133 (сбои подключения Claude.ai) и Issue #108 (баг пути аудитории RFC 8707)