github-mcp-proxy

Cloudflare Workers에서 실행되는 자체 호스팅 GitHub MCP 서버로, AI 에이전트를 위한 저장소별 가드레일을 제공하여 개인 또는 소규모 팀이 사용하기에 적합합니다.

MCP를 지원하는 모든 에이전트(Claude, Codex, ChatGPT, Cursor, Cline 등)를 연결할 수 있으며, 에이전트가 어떤 저장소에 접근할 수 있고 어떻게 상호작용할지 엄격하게 제어할 수 있습니다.

[!WARNING] 보안이나 안정성이 중요하다면 공식 GitHub MCP 서버를 사용하세요. 자유롭게 포크하여 사용하시되, 포크 이후의 보안 문제는 사용자 본인의 책임입니다.

목적

일반적인 GitHub 토큰은 에이전트에게 계정 전체에 대한 접근 권한을 부여합니다. 이 서버는 다음과 같이 권한을 제한합니다:

• 저장소별 권한 수준 — read / issues / full

• 브랜치 보호 — 새 브랜치는 반드시 특정 접두사(기본값 claude/)를 따라야 하며, main/master 브랜치는 수정할 수 없습니다.

• 커밋 메시지 정책 — 서버 측에서 검증되는 Conventional Commits 준수

• 라벨 화이트리스트 — 저장소별 allowedLabels 설정; 서버는 GitHub에서 라벨을 자동으로 생성하지 않습니다.

• 금지된 경로 — .github/workflows/**는 항상 차단됩니다.

• 감사 추적 — 모든 쓰기 작업 시 Signed-off-by / Assisted-by 트레일러나 에이전트 및 모델 정보를 식별하는 푸터가 자동으로 추가됩니다.

Related MCP server: Kontrol

아키텍처

 MCP agent ──(Streamable HTTP + OAuth)──▶ Cloudflare Worker
                                              │
                                              ├── workers-oauth-provider  (OAuth 2.1 server to MCP clients)
                                              ├── GitHub OAuth            (OAuth client to github.com)
                                              ├── KV                      (session tokens)
                                              ├── Durable Object          (MCP agent state)
                                              └── Octokit                 (GitHub REST)

설정(ghmcp.config.ts)은 배포 시점에 워커와 함께 번들로 제공되므로 런타임 KV 읽기가 필요 없으며 satisfies를 통해 타입 체크가 수행됩니다.

빠른 시작

git clone <your-fork>
cd kz-github-mcp
npm install
cp ghmcp.config.sample.ts ghmcp.config.ts   # edit: repos you want to expose
cp wrangler.sample.jsonc wrangler.jsonc      # edit: KV id + worker name
cp .env.example .env                         # edit: for local dev only

GitHub OAuth 앱을 생성합니다(홈페이지 = https://<worker>.<subdomain>.workers.dev, 콜백 = /callback). 그 후:

wrangler kv namespace create "OAUTH_KV"      # add the id to wrangler.jsonc
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY    # openssl rand -hex 32
npm run deploy

로컬 개발: http://localhost:8788을 가리키는 두 번째 OAuth 앱으로 동일한 흐름을 수행하고, .env에 자격 증명을 설정한 뒤 npm run dev를 실행합니다.

지속적 배포 (선택 사항)

.github/workflows/deploy.yml은 main 브랜치에 푸시할 때마다 Cloudflare에 배포합니다. GitHub 설정 → Secrets and variables → Actions에서 두 개의 저장소 시크릿을 설정하세요:

GitHub OAuth 자격 증명(GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY)은 GitHub Actions가 아닌 워커 자체의 Wrangler 시크릿으로 저장됩니다. wrangler secret put을 사용하여 한 번만 설정하면 됩니다.

작동 방식은 docs/ARCHITECTURE.md를, 모든 설정 필드는 docs/CONFIG.md를 참조하세요.

AI 에이전트 연결

Claude (claude.ai) — 설정 → 커넥터 → 사용자 지정 커넥터 추가 → https://<worker>.<subdomain>.workers.dev/sse를 붙여넣습니다.

Claude Code / Codex / Cursor / Cline — 클라이언트의 MCP 설정에 추가합니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["mcp-remote", "https://<worker>.<subdomain>.workers.dev/sse"]
    }
  }
}

모든 MCP 호스트 — 동일한 /sse 엔드포인트를 가리키도록 설정합니다. 첫 연결 시 OAuth 흐름이 실행됩니다.

에이전트가 도구를 올바르게 사용하도록 가르치려면 시스템 프롬프트 / 프로젝트 지침 / 스킬 디렉토리에 SKILL.md를 포함하세요.

도구

ghmcp_ 접두사가 붙습니다. 각 도구는 최소 권한 수준을 선언하며, 서버는 그보다 낮은 수준의 호출을 거부합니다.

모든 도구는 설정의 disabledTools를 통해 비활성화할 수 있습니다.

npm run validate-config

gh CLI를 사용하여 ghmcp.config.ts의 모든 저장소가 존재하는지, allowedLabels의 모든 라벨이 GitHub에 존재하는지 확인합니다. prebuild 훅으로 자동 실행되므로 오타가 있으면 npm run build가 실패합니다.

라이선스

원래 cloudflare/ai/demos/remote-mcp-github-oauth에서 포크되었습니다. MIT 라이선스를 따릅니다.

이 도구는 MIT 라이선스 하에 있습니다. — LICENSE를 참조하세요.