Model Context Protocol (MCP) 서버 + Github OAuth

이것은 원격 MCP 연결을 지원하는 Model Context Protocol (MCP) 서버로, Github OAuth가 내장되어 있습니다.

자신의 Cloudflare 계정에 배포하고, 자신만의 Github OAuth 클라이언트 앱을 만든 후에는 그 위에 구축할 수 있는 완전한 기능의 원격 MCP 서버를 갖게 됩니다. 사용자는 GitHub 계정으로 로그인하여 MCP 서버에 연결할 수 있습니다.

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

MCP 서버(Cloudflare Workers 기반)는:

• MCP 클라이언트에게 OAuth 서버 역할을 합니다

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

[!WARNING] 이것은 빠르게 시작할 수 있도록 설계된 데모 템플릿입니다. 여러 보안 제어 기능을 구현했지만, 프로덕션에 배포하기 전에 모든 예방 및 심층 방어 보안 조치를 구현해야 합니다. 포괄적인 보안 가이드를 검토하세요: MCP 서버 보안

시작하기

저장소를 직접 클론하고 의존성을 설치하세요: npm install.

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

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

프로덕션용

새 GitHub OAuth 앱을 만드세요:

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

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

• Client ID를 기록하고 Client secret을 생성하세요

• 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

[!IMPORTANT] 첫 번째 시크릿을 생성할 때 Wrangler가 새 Worker를 생성할지 묻습니다. "Y"를 제출하여 새 Worker를 생성하고 시크릿을 저장하세요.

KV 네임스페이스 설정

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

• KV ID로 Wrangler 파일을 업데이트하세요

배포 및 테스트

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

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

npx @modelcontextprotocol/inspector@latest

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

이제 원격 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을 열고 Settings -> Developer -> Edit Config로 이동하세요. 그러면 Claude가 접근할 수 있는 MCP 서버를 제어하는 구성 파일이 열립니다.

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

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

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

로컬 개발용

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

• Homepage URL에 http://localhost:8788을 지정하세요

• Authorization callback URL에 http://localhost:8788/callback을 지정하세요

• Client ID를 기록하고 Client secret을 생성하세요

• 프로젝트 루트에 .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를 입력하고 연결을 누르세요. 프롬프트를 따라가면 "List Tools"를 할 수 있습니다.

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

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

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

Cursor를 MCP 서버에 연결하려면 Type에서 "Command"를 선택하고 Command 필드에 command와 args 필드를 하나로 결합하세요(예: npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse).

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

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

어떻게 작동하나요?

OAuth 제공자

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

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

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

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

Durable MCP

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

• MCP 서버의 영구 상태 관리

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

• this.props를 통한 인증된 사용자 정보 접근

• 사용자 신원에 따른 조건부 도구 사용 가능 여부 지원

MCP Remote

MCP Remote 라이브러리는 서버가 Inspector와 같은 MCP 클라이언트가 호출할 수 있는 도구를 노출할 수 있게 합니다. 다음을 수행합니다:

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

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

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

• 클라이언트와 서버 간 Server-Sent Events (SSE) 연결 유지