Remote MCP Server with GitHub OAuth

모델 컨텍스트 프로토콜(MCP) 서버 + Github OAuth

Github OAuth가 내장되어 원격 MCP 연결을 지원하는 MCP(Model Context Protocol) 서버입니다.

Cloudflare 계정에 배포할 수 있으며, Github OAuth 클라이언트 앱을 직접 생성하면 완벽하게 작동하는 원격 MCP 서버를 구축할 수 있습니다. 사용자는 GitHub 계정으로 로그인하여 MCP 서버에 연결할 수 있습니다.

workers-oauth-provider 라이브러리를 사용하여 Cloudflare에 배포된 MCP 서버와 다른 OAuth 공급자를 통합하는 방법에 대한 참조 예로 사용할 수 있습니다.

MCP 서버( Cloudflare Workers 기반):

• MCP 클라이언트에 대한 OAuth 서버 역할을 합니다.
• 실제 OAuth 서버(이 경우 GitHub)에 대한 OAuth 클라이언트 역할을 합니다.

시작하기

저장소를 직접 복제하고 종속성을 설치합니다: npm install .

또는 아래 명령줄을 사용하여 로컬 컴퓨터에 원격 MCP 서버를 생성할 수 있습니다.

지엑스피1

생산을 위해

새로운 GitHub OAuth 앱을 만듭니다.

• 홈페이지 URL에 https://mcp-github-oauth.<your-subdomain>.workers.dev 지정하세요.
• 권한 부여 콜백 URL에 대해 https://mcp-github-oauth.<your-subdomain>.workers.dev/callback 지정합니다.
• 클라이언트 ID를 기록하고 클라이언트 비밀번호를 생성하세요.
• Wrangler를 통해 비밀 설정

KV 네임스페이스 설정

• KV 네임스페이스를 생성합니다: wrangler kv:namespace create "OAUTH_KV"
• KV ID로 Wrangler 파일을 업데이트합니다.

배포 및 테스트

MCP 서버를 배포하여 workers.dev 도메인에서 사용할 수 있도록 합니다 wrangler deploy

Inspector를 사용하여 원격 서버를 테스트합니다.

https://mcp-github-oauth.<your-subdomain>.workers.dev/sse 입력하고 연결을 클릭하세요. 인증 절차를 거치면 도구가 작동하는 것을 볼 수 있습니다.

이제 원격 MCP 서버가 배포되었습니다!

접근 제어

이 MCP 서버는 인증에 GitHub OAuth를 사용합니다. 인증된 모든 GitHub 사용자는 "add" 및 "userInfoOctokit"과 같은 기본 도구에 액세스할 수 있습니다.

"generateImage" 도구는 ALLOWED_USERNAMES 구성에 나열된 특정 GitHub 사용자로 제한됩니다.

Claude Desktop에서 원격 MCP 서버에 액세스

Claude Desktop을 열고 설정 -> 개발자 -> 구성 편집으로 이동합니다. 그러면 Claude가 액세스할 수 있는 MCP 서버를 제어하는 구성 파일이 열립니다.

다음 구성으로 콘텐츠를 바꾸세요. Claude Desktop을 다시 시작하면 OAuth 로그인 페이지가 표시된 브라우저 창이 열립니다. 인증 흐름을 완료하여 Claude에게 MCP 서버 접근 권한을 부여하세요. 접근 권한을 부여하면 도구를 사용할 수 있게 됩니다.

인터페이스에 도구(🔨 아래)가 표시되면 Claude에게 도구를 사용해 달라고 요청할 수 있습니다. 예: "수학 도구를 사용하여 23과 19를 더해 주시겠어요?" Claude는 도구를 호출하여 MCP 서버에서 생성된 결과를 표시합니다.

지역 개발을 위해

MCP 서버를 반복하고 테스트하려면 로컬 개발 환경에서 수행할 수 있습니다. 이를 위해서는 GitHub에 OAuth 앱을 하나 더 만들어야 합니다.

• 홈페이지 URL에 http://localhost:8788 지정하세요.
• 권한 부여 콜백 URL에 대해 http://localhost:8788/callback 지정하세요.
• 클라이언트 ID를 기록하고 클라이언트 비밀번호를 생성하세요.
• 프로젝트 루트에 .dev.vars 파일을 다음과 같이 만듭니다.

개발 및 테스트

서버를 로컬로 실행하여 http://localhost:8788 wrangler dev 에서 사용할 수 있도록 합니다.

로컬 서버를 테스트하려면 Inspector에 http://localhost:8788/sse 입력하고 연결을 클릭하세요. 안내에 따라 진행하면 "도구 목록"을 볼 수 있습니다.

Claude 및 기타 MCP 클라이언트 사용

Claude를 사용하여 원격 MCP 서버에 연결할 때 오류 메시지가 표시될 수 있습니다. 이는 Claude Desktop이 아직 원격 MCP 서버를 지원하지 않아 가끔 혼동이 발생하기 때문입니다. MCP 서버가 연결되었는지 확인하려면 Claude 인터페이스 오른쪽 하단에 있는 🔨 아이콘에 마우스를 올려보세요. 사용 가능한 도구가 표시됩니다.

커서 및 기타 MCP 클라이언트 사용

Cursor를 MCP 서버에 연결하려면 Type : "명령"을 선택하고 Command 필드에서 명령 필드와 인수 필드를 하나로 결합합니다(예 npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse ).

Cursor는 HTTP+SSE 서버를 지원하지만 인증은 지원하지 않으므로 여전히 mcp-remote 사용해야 합니다(그리고 HTTP 서버가 아닌 STDIO 서버를 사용해야 합니다).

Windsurf와 같은 다른 MCP 클라이언트에 MCP 서버를 연결하려면 클라이언트의 구성 파일을 열고 Claude 설정에 사용된 것과 동일한 JSON을 추가한 다음 MCP 클라이언트를 다시 시작하세요.

어떻게 작동하나요?

OAuth 공급자

OAuth Provider 라이브러리는 Cloudflare Workers를 위한 완전한 OAuth 2.1 서버 구현체입니다. 토큰 발급, 유효성 검사 및 관리를 포함한 OAuth 흐름의 복잡한 부분을 처리합니다. 이 프로젝트에서는 다음과 같은 두 가지 역할을 수행합니다.

• 서버에 연결하는 MCP 클라이언트 인증
• GitHub의 OAuth 서비스에 대한 연결 관리
• KV 스토리지에 토큰과 인증 상태를 안전하게 저장

내구성이 뛰어난 MCP

내구성 있는 MCP는 Cloudflare의 내구성 있는 객체를 통해 기본 MCP 기능을 확장하여 다음을 제공합니다.

• MCP 서버에 대한 지속적인 상태 관리
• 요청 간 인증 컨텍스트의 안전한 저장
• this.props 를 통해 인증된 사용자 정보에 액세스
• 사용자 ID에 따른 조건부 도구 가용성 지원

MCP 원격

MCP Remote 라이브러리를 사용하면 서버에서 Inspector와 같은 MCP 클라이언트에서 호출할 수 있는 도구를 노출할 수 있습니다. 다음과 같은 기능을 제공합니다.

• 클라이언트와 서버 간 통신을 위한 프로토콜을 정의합니다.
• 도구를 정의하는 체계적인 방법을 제공합니다.
• 요청 및 응답의 직렬화 및 역직렬화를 처리합니다.
• 클라이언트와 서버 간의 SSE(Server-Sent Events) 연결을 유지합니다.