GitHub MCP Wrapper for claude.ai
claude.ai 웹/앱의 커스텀 커넥터에서 공식 GitHub MCP 서버에 붙기 위한 OAuth 래퍼.
왜 필요한가
claude.ai 커스텀 커넥터는 MCP OAuth 스펙(protected-resource 메타데이터, DCR, PKCE, https://claude.ai/api/mcp/auth_callback 콜백)을 따르는 서버만 붙는다. GitHub OAuth App을 그대로 꽂으면 이 디스커버리 흐름을 못 맞춰서 토큰 없이 호출 → 401 → "토큰 없음" 에러로 떨어진다.
이 래퍼는 앞단에서 claude.ai가 요구하는 OAuth를 충족하고(게이트는 비밀번호 하나), 통과하면 네 GitHub PAT를 달아서 공식 GitHub MCP(api.githubcopilot.com/mcp/)로 프록시한다. 공식 서버의 전체 툴셋(레포·이슈·PR·Actions·gist 읽기/쓰기)을 그대로 쓴다.
상태 저장은 서명된 토큰(HMAC-SHA256)으로 처리 → DB·외부 서비스 불필요.
1. GitHub PAT 발급
github.com/settings/tokens 에서 발급.
- Classic:
repo,read:org,workflow,gist(쓰기까지 원하면 이 정도) - Fine-grained: 대상 레포 + Contents/Issues/Pull requests/Actions = Read and write
발급된 토큰 문자열을 복사해둔다.
2. Vercel 배포
이 폴더를 GitHub 레포에 올린 뒤 Vercel에서 Import, 또는 CLI:
npm i -g vercel
vercel
vercel --prod배포되면 도메인이 나온다. 예: https://gh-mcp-wrapper.vercel.app
환경변수 (Vercel → Project → Settings → Environment Variables)
| 이름 | 값 | |------|----| | GITHUB_PAT | 1단계에서 발급한 토큰 | | AUTH_PASSWORD | 커넥터 연결 시 입력할 비밀번호 (직접 정함) | | SIGNING_SECRET | 긴 랜덤 문자열 (openssl rand -hex 32) |
세 개 다 넣고 재배포(vercel --prod).
동작 확인
curl https://<도메인>/.well-known/oauth-authorization-serverJSON에 authorization_endpoint, token_endpoint, registration_endpoint가 보이면 정상.
3. claude.ai 커넥터 추가
설정 → 커넥터 → 커스텀 커넥터 추가:
- 이름: 아무거나 (예: GitHub)
- 원격 MCP 서버 URL:
https://<도메인>/mcp - 고급 설정의 OAuth 클라이언트 ID / 시크릿: 비워둔다 (DCR이 처리)
추가 → 연결(Connect) → 브라우저에 비밀번호 입력창 → AUTH_PASSWORD 입력 → 승인되면 툴 활성화.
엔드포인트
| 경로 | 역할 | |------|------| | /.well-known/oauth-protected-resource | RFC 9728 메타데이터 | | /.well-known/oauth-authorization-server | AS 메타데이터 | | /register | Dynamic Client Registration | | /authorize | 비밀번호 게이트 + 코드 발급 | | /token | 코드/리프레시 → 액세스 토큰 | | /mcp | 토큰 검증 후 공식 GitHub MCP로 프록시 |
주의
- claude.ai 커스텀 커넥터 OAuth 자체에 알려진 버그가 있다(인증 후 후속 요청에
Authorization 헤더 누락 등). 래퍼가 정상이어도 claude.ai 쪽 이슈로 한 번에 안 붙을 수 있다. 그 경우 커넥터 삭제 후 재추가, 새 대화에서 재시도.
- PAT는 GitHub에서 만료/스코프 조정 가능. 만료되면 Vercel 환경변수만 교체.
- 단일 사용자 전제. URL이 노출돼도 비밀번호가 게이트지만,
SIGNING_SECRET과
AUTH_PASSWORD는 충분히 길게.
