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-server

JSON에 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는 충분히 길게.