Model Context Protocol (MCP) 서버 + Github OAuth

이 서버는 Model Context Protocol (MCP) 서버로, Github OAuth가 내장된 원격 MCP 연결을 지원합니다.

자신의 Cloudflare 계정에 배포하고 직접 Github OAuth 클라이언트 앱을 생성하면, 이를 기반으로 확장 가능한 완전한 기능의 원격 MCP 서버를 구축할 수 있습니다. 사용자는 자신의 GitHub 계정으로 로그인하여 귀하의 MCP 서버에 연결할 수 있습니다.

이 프로젝트는 workers-oauth-provider 라이브러리를 사용하여 Cloudflare에 배포된 MCP 서버에 다른 OAuth 제공자를 통합하는 방법을 보여주는 참조 예제로 사용할 수 있습니다.

이 MCP 서버(Cloudflare Workers 기반)는 다음과 같은 역할을 합니다:

• MCP 클라이언트에 대한 OAuth 서버 역할

• 실제 OAuth 서버(이 경우 GitHub)에 대한 OAuth 클라이언트 역할

시작하기

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

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

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-github-oauth

프로덕션 환경

새로운 GitHub OAuth 앱을 생성하세요:

• 홈페이지 URL에는 https://mcp-github-oauth.<your-subdomain>.workers.dev를 지정하세요.

• 인증 콜백 URL에는 https://mcp-github-oauth.<your-subdomain>.workers.dev/callback을 지정하세요.

• 클라이언트 ID를 기록하고 클라이언트 시크릿을 생성하세요.

• Wrangler를 통해 시크릿을 설정하세요.

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

KV 네임스페이스 설정

• KV 네임스페이스 생성: wrangler kv:namespace create "OAUTH_KV"

• Wrangler 파일에 KV ID 업데이트

배포 및 테스트

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

Inspector를 사용하여 원격 서버를 테스트하세요:

npx @modelcontextprotocol/inspector@latest

https://mcp-github-oauth.<your-subdomain>.workers.dev/sse를 입력하고 연결을 누르세요. 인증 흐름을 완료하면 도구가 작동하는 것을 확인할 수 있습니다:

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

액세스 제어

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

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

// Add GitHub usernames for image generation access
const ALLOWED_USERNAMES = new Set([
  'yourusername',
  'teammate1'
]);

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

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

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

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

인터페이스에 도구(🔨 아래)가 나타나면 Claude에게 사용을 요청할 수 있습니다. 예: "math 도구를 사용하여 23과 19를 더해줄래?". Claude가 도구를 호출하고 MCP 서버에서 생성된 결과를 보여줄 것입니다.

로컬 개발

MCP 서버를 반복적으로 테스트하려면 로컬 개발 환경에서 수행할 수 있습니다. 이를 위해서는 GitHub에서 다른 OAuth 앱을 생성해야 합니다:

• 홈페이지 URL에는 http://localhost:8788을 지정하세요.

• 인증 콜백 URL에는 http://localhost:8788/callback을 지정하세요.

• 클라이언트 ID를 기록하고 클라이언트 시크릿을 생성하세요.

• 프로젝트 루트에 .dev.vars 파일을 생성하고 다음을 입력하세요:

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret

개발 및 테스트

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

로컬 서버를 테스트하려면 Inspector에 http://localhost:8788/sse를 입력하고 연결을 누르세요. 프롬프트를 따르면 "도구 목록"을 확인할 수 있습니다.

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

Claude를 사용하여 원격 MCP 서버에 연결할 때 일부 오류 메시지가 표시될 수 있습니다. 이는 Claude Desktop이 아직 원격 MCP 서버를 완전히 지원하지 않아 가끔 혼동을 일으키기 때문입니다. MCP 서버가 연결되었는지 확인하려면 Claude 인터페이스 오른쪽 하단의 🔨 아이콘 위에 마우스를 올리세요. 거기에서 사용 가능한 도구를 확인할 수 있어야 합니다.

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

Cursor를 MCP 서버에 연결하려면 Type을 "Command"로 선택하고 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 클라이언트를 다시 시작하면 됩니다.

Related MCP server: GitHub MCP Server

작동 원리

라이선스

이 프로젝트는 GPL-3.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

OAuth 제공자

OAuth 제공자 라이브러리는 Cloudflare Workers를 위한 완전한 OAuth 2.1 서버 구현을 제공합니다. 토큰 발급, 검증 및 관리를 포함한 OAuth 흐름의 복잡성을 처리합니다. 이 프로젝트에서 다음과 같은 이중 역할을 수행합니다:

• 서버에 연결하는 MCP 클라이언트 인증

• GitHub의 OAuth 서비스에 대한 연결 관리

• KV 저장소에 토큰 및 인증 상태를 안전하게 저장

Durable MCP

Durable MCP는 Cloudflare의 Durable Objects를 사용하여 기본 MCP 기능을 확장하며 다음을 제공합니다:

• MCP 서버를 위한 지속적인 상태 관리

• 요청 간 인증 컨텍스트의 안전한 저장

• this.props를 통한 인증된 사용자 정보 액세스

• 사용자 ID에 따른 조건부 도구 가용성 지원

MCP Remote

MCP Remote 라이브러리를 사용하면 서버가 Inspector와 같은 MCP 클라이언트에 의해 호출될 수 있는 도구를 노출할 수 있습니다. 이 라이브러리는:

• 클라이언트와 서버 간 통신 프로토콜 정의

• 도구를 정의하는 구조화된 방법 제공

• 요청 및 응답의 직렬화 및 역직렬화 처리

• 클라이언트와 서버 간의 서버 전송 이벤트(SSE) 연결 유지