github-mcp-gateway

모든 MCP 클라이언트에 인증된 GitHub 액세스(저장소, 이슈, 풀 리퀘스트, 파일 내용, 검색)를 실제 OAuth 2.1 핸드셰이크를 통해 Cloudflare Workers에서 제공하는 원격 MCP 서버입니다.

Claude Code, Claude.ai / Cowork 및 사양을 준수하는 모든 MCP 클라이언트와 함께 작동합니다. 인증은 GitHub App 사용자-서버 흐름이므로, 이 서버가 도달할 수 있는 저장소는 GitHub의 설치 화면에서 직접 선택한 저장소뿐입니다. 계정에서 볼 수 있는 모든 것이 아닙니다.

이것은 가입하는 서비스가 아니라 직접 실행하는 소스입니다. 공유 인스턴스는 없습니다. 자신의 GitHub App에 대해 자신의 Worker를 배포하며, 자격 증명이 계정 밖으로 나가지 않습니다 — 설계 제한을 참조하세요. 설정은 스크립트 하나와 약 10분이면 됩니다:

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에 직접 접근할 수 없습니다. 사이에 (a) 누가 요청하는지 증명하고, (b) 실제 GitHub 토큰을 보유하고, (c) 도구 호출을 GitHub API 요청으로 변환하는 무언가가 필요합니다. 이 Worker가 바로 그 중간 계층이며, 한 번에 두 가지 OAuth 역할을 수행합니다:

• OAuth 클라이언트 — GitHub(업스트림)에 대한 역할. 사용자를 GitHub의 동의 화면으로 보내고 결과 코드를 토큰으로 교환합니다.

• OAuth 서버 — MCP 클라이언트(다운스트림)에 대한 역할. 클라이언트는 사용자의 GitHub 토큰을 볼 수 없습니다. 이 Worker에서 이 Worker에만 범위가 제한된 자체 토큰을 받습니다. @cloudflare/workers-oauth-provider(Cloudflare 자체 라이브러리)가 그 다운스트림 절반을 구현합니다: 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

왜 클래식 OAuth App 대신 GitHub App인가

Cloudflare 자체 템플릿은 클래식 OAuth App을 사용합니다. 더 단순하지만 저장소 범위가 전부 아니면 전무(all-or-nothing)이고, 직접 만료를 구현하지 않는 한 토큰이 만료되지 않습니다. 이 빌드는 대신 user-to-server 토큰 흐름을 사용하는 GitHub App을 사용합니다:

• 설치 시 저장소별 범위 지정 — 이 서버가 접근할 수 있는 저장소를 정확히 선택합니다(GitHub 자체 설치 선택기). "이 계정이 볼 수 있는 모든 것"이 아닙니다.

• 실제로 만료되고 자동으로 갱신되는 토큰 — "Expire user authorization tokens"을 켜면 GitHub가 8시간 액세스 토큰과 6개월 리프레시 토큰을 돌려주고, 리프레시 토큰을 사용하면 두 토큰의 새 쌍이 발급됩니다. 이 서버를 6개월에 한 번 이상만 사용하면 토큰이 유효기간이 지나지 않으며 수동으로 새 토큰을 발급할 필요가 없습니다.

이 갱신 주기는 src/github-client.ts에서 처리되며, Cowork와 이 Worker 사이의 자체 세션과는 독립적입니다 — 아래 토큰 수명 주기를 참조하세요.

1. GitHub App 만들기

github.com/settings/apps/new(개인 계정) 또는 github.com/organizations/<org>/settings/apps/new(조직 소유 — 개인 계정이 아니라 조직 아래에 두려면 이쪽을 사용)로 이동하세요.

만든 후:

1. 앱 설정 페이지 상단의 Client ID를 기록해 두세요.

2. Generate a new client secret을 클릭하세요 — 지금 복사하세요. 한 번만 표시됩니다.

3. Optional features에서 User-to-server token expiration을 찾아 Opt-in을 클릭하세요. 이것이 리프레시 토큰이 존재하도록 만드는 기능입니다. 건너뛰면 서버가 콜백 단계에서 이 작업을 하라고 안내하는 명확한 오류와 함께 실패할 것입니다.

4. Install App(왼쪽 사이드바)으로 이동해 계정에 설치하고, Only select repositories를 선택하세요 — 이 서버가 접근하려는 저장소를 고르면 됩니다(같은 화면에서 나중에 추가할 수 있습니다).

배포 전에 로컬에서 wrangler dev로 반복 작업할 계획이라면, 동일하게 구성되지만 콜백 URL이 http://localhost:8788/callback인 두 번째 GitHub App이 필요합니다.

2. KV 네임스페이스 만들기

가장 빠른 방법 — ./scripts/setup.sh <your-github-login> 은 의존성을 설치하고, 네임스페이스를 만들고, wrangler.jsonc에 네임스페이스 id와 허용 목록을 다시 써 줍니다. 그런 다음 3단계로 건너뛰세요.

수동으로 하려면:

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

반환된 id를 wrangler.jsonc의 kv_namespaces[0].id에 복사하되, 커밋된 값을 교체하세요. 그 값은 플레이스홀더가 아니라 메인테이너의 라이브 네임스페이스입니다. 이 저장소는 템플릿이면서 동시에 실행 중인 배포이므로 체크인된 설정이 실제 값입니다. 그것은 식별자이지 자격 증명이 아닙니다. 포크에 아무것도 부여하지 않지만, 그대로 두면 Worker가 사용자 계정에서 접근할 수 없는 네임스페이스를 대상으로 시작됩니다.

3. 시크릿과 허용 목록 변수 설정

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는 시크릿이 아니라 일반 변수입니다. wrangler.jsonc의 최상위 "vars" 블록에 추가하세요:

"vars": {
  "ALLOWED_GITHUB_LOGINS": "your-github-login"
}

이것은 OAuth 콜백에서 검사되는 심층 방어(defense-in-depth) 허용 목록입니다. GitHub 동의 화면은 당신 계정에 대해 오직 당신만 완료할 수 있지만, 이렇게 하면 "인증할 수 있는 사람이라면 누구나"라는 암묵적 허용이 아니라 코드에 명시적인 게이트가 됩니다. 설정되지 않았거나 비어 있으면 모든 사람을 거부합니다. 즉, 실패 시 닫히는(fail closed) 방식이므로, 단계를 빠뜨리면 서버가 열리는 대신 접근이 차단됩니다.

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: 해당 URL로 사용자 지정 MCP 커넥터를 추가하세요.

클라이언트는 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. workers-oauth-provider가 발급한 표준 OAuth 2.1 액세스/리프레시 토큰. Cowork는 MCP 사양에 따라 이를 자동으로 자체 갱신합니다 — 관리할 것이 없습니다.

2. 이 Worker ↔ GitHub. 8시간 액세스 토큰 + 6개월 리프레시 토큰. src/github-client.ts는 모든 GitHub API 호출 전에 만료를 확인하고 만료 5분 이내일 때 투명하게 갱신하여 회전된 쌍을 OAUTH_KV의 github:tokens:{your-login} 아래에 저장합니다. 이것은 의도적으로 workers-oauth-provider의 tokenExchangeCallback 훅을 통해 연결되지 않습니다 — 그 메커니즘에는 해결되지 않은 업스트림 버그가 있습니다(갱신 후 props가 오래되어 재인증 루프가 발생함; 참조 자료 참조) — 그래서 대신 툴 계층에서 직접 처리하는데, 이쪽이 추론하고 테스트하기 더 간단합니다.

GitHub의 리프레시 토큰 자체가 만료되거나(6개월 이상 사용하지 않음) 앱 액세스를 해지하면, 다음 도구 호출은 명확한 ReauthorizationRequiredError 메시지와 함께 실패하며, Cowork에서 연결을 끊고 다시 연결하라고 안내합니다. 여기에는 조용한 실패 모드가 없습니다 — 백그라운드에서 조용히 작동하거나, 정확히 무엇을 해야 하는지 알려줍니다.

도구

모든 목록 도구는 페이지네이션을 위해 per_page와 page를 받습니다.

github_merge_pull_request와 github_delete_file은 두 가지 파괴적인 작업입니다. 호출된 후에는 도구 자체로 되돌릴 수 없습니다. 클라이언트는 둘 중 하나를 호출하기 전에 사용자에게 확인을 받아야 합니다.

github_update_repo(description, homepage, topics)를 사용하려면 GitHub 앱에 Administration 리포지토리 권한이 필요합니다. 현재 구성된 앱(Contents/Issues/PRs/Metadata)에는 이 권한이 포함되어 있지 않습니다. 앱 설정에서 권한을 추가하고 설치를 다시 승인하면 이 도구를 사용할 수 있습니다. 또는 gh CLI로 해당 편집을 수행하세요.

설계 제한(의도적)

도입하기 전에 읽어보세요. 이는 결함이 아니라 설계 결정입니다.

배포당 운영자 1명

이 서버는 의도적으로 단일 테넌트(single-tenant) 방식입니다. ALLOWED_GITHUB_LOGINS가 OAuth 콜백을 제어하며, 쉼표로 구분된 목록을 허용하고 토큰 저장도 이미 로그인별로 키가 지정되어 있지만(github:tokens:{login}), 의도된 형태는 사람마다 배포 1개입니다.

이는 위협 모델 결정입니다. 공유 배포라면 한 운영자의 KV 네임스페이스에 다른 사람의 GitHub refresh token — 리포지토리 쓰기 액세스 권한이 있는 6개월 자격 증명 — 이 저장된다는 뜻입니다. 그렇게 되면 운영자는 그러한 보증이 없는 인프라에서 침해 통지 의무가 있는 자격 증명 관리자가 됩니다. 셀프 호스팅은 모든 자격 증명이 해당 계정에만 유지되도록 하며, 이것이 이 설계의 핵심입니다.

그러니 포크해서 직접 실행하세요. ./scripts/setup.sh가 정확히 그 용도로 존재합니다. 설정은 대략 10분 정도 걸리며 Cloudflare 무료 티어로 개인 사용은 충분합니다.

리포지토리 범위는 이 서버가 아니라 설치 시점에 결정됩니다.

이것은 클래식 OAuth 앱이 아니라 GitHub *앱(App)*이므로 이를 통해 접근할 수 있는 리포지토리는 GitHub의 설치 화면에서 직접 선택한 리포지토리입니다. 이 서버는 그 범위를 넓힐 수 없으며, 어떤 도구 호출도 그 밖으로 나갈 수 없습니다. 범위를 변경하려면 설치를 변경하세요.

github_update_repo에는 앱에 기본 포함되지 않은 권한이 필요합니다.

Administration 리포지토리 권한이 필요합니다. 앱 설정에서 권한을 추가하고 설치를 다시 승인하거나, gh CLI를 사용하여 description 및 topic을 편집하세요.

호스팅 서비스가 아님

클라이언트가 지정할 수 있는 공개 인스턴스는 없습니다. 이 리포지토리에서(deploy.yml, SECURITY.md 또는 Dockerfile 헤더에서) 찾을 수 있는 workers.dev URL은 전부 관리자 본인의 배포이며, 그 허용 목록은 여러분을 거부합니다. 이것은 가입해서 사용하는 서비스가 아니라 직접 실행하는 소스 코드입니다.

보안 참고 사항 / 이 빌드가 고려하는 알려진 업스트림 문제

• CSRF, state 재생, 세션 고정 — src/oauth/workers-oauth-utils.ts에서 처리합니다. 동의 양식의 CSRF 토큰 + 쿠키 쌍, 일회용 KV 지원 state(10분 TTL), 그리고 GitHub 콜백을 완료하는 브라우저가 흐름을 시작한 바로 그 브라우저임을 증명하는 세션 바인딩 쿠키(state 토큰의 SHA-256 해시)를 통해 처리합니다.

• workers-oauth-provider Issue #133 — audience 검증의 경로 처리 버그로 인해 일부 버전에서는 특히 Claude.ai/Cowork 연결이 끊어졌습니다. 이 빌드는 문서화된 해결 방법대로 리소스 표시자에 경로 구성 요소를 추가하지 않습니다(/mcp 및 /sse 라우트는 더 긴 경로 아래 중첩되지 않고 apiHandlers의 루트에 등록됨). Cowork의 첫 연결 시도가 토큰 교환 단계에서 실패하면 이것이 가장 먼저 확인할 업스트림 항목입니다.

• Issue #108(경로가 있는 RFC 8707 audience 검증) — 위와 동일한 근본 원인, 동일한 완화 조치.

• Issue #29(프로덕션에서 redirect URI 불일치) — 일부 클라이언트의 경우 DCR로 등록된 redirect URI가 프로덕션에서 wrangler dev와 다르게 동작하는 것으로 보고되었습니다. Cowork의 리디렉션이 배포 후에만 실패하고(로컬에서는 작동) 있다면 이것이 알려진 용의자입니다.

• __Host- 쿠키 접두어를 전체적으로 사용 — 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 경로 audience 버그)