MCP Server with GitHub OAuth

Um servidor MCP remoto com suporte integrado ao GitHub OAuth, projetado para implantação no Cloudflare Workers.

GitHubExperimente este MCPPatrocinado

Documentação

Model Context Protocol (MCP) Server + Github OAuth

Este é um servidor Model Context Protocol (MCP) que suporta conexões MCP remotas, com OAuth do Github integrado.

Você pode implantá-lo na sua própria conta Cloudflare e, após criar seu próprio aplicativo de cliente OAuth do GitHub, terá um servidor MCP remoto totalmente funcional que poderá usar como base. Os usuários poderão se conectar ao seu servidor MCP fazendo login com suas contas GitHub.

Você pode usar este projeto como exemplo de referência para integrar outros provedores OAuth a um servidor MCP implantado na Cloudflare, usando a biblioteca workers-oauth-provider.

O servidor MCP (alimentado por Cloudflare Workers):

  • Atua como Servidor OAuth para seus clientes MCP
  • Atua como Cliente OAuth para seu servidor OAuth real (neste caso, GitHub)

Começando

Clone o repositório diretamente e instale as dependências: npm install.

Alternativamente, você pode usar a linha de comando abaixo para criar o servidor MCP remoto na sua máquina local:

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

Para Produção

Crie um novo Aplicativo OAuth do GitHub:

  • Para a URL da página inicial, especifique https://mcp-github-oauth.<your-subdomain>.workers.dev
  • Para a URL de callback de autorização, especifique https://mcp-github-oauth.<your-subdomain>.workers.dev/callback
  • Anote seu Client ID e gere um Client secret.
  • Defina os segredos via 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

Configure um namespace KV

  • Crie o namespace KV: wrangler kv:namespace create "OAUTH_KV"
  • Atualize o arquivo Wrangler com o ID do KV

Implante e Teste

Implante o servidor MCP para disponibilizá-lo no seu domínio workers.dev wrangler deploy

Teste o servidor remoto usando o Inspector:

npx @modelcontextprotocol/inspector@latest

Digite https://mcp-github-oauth.<your-subdomain>.workers.dev/sse e clique em conectar. Depois de passar pelo fluxo de autenticação, você verá as Ferramentas funcionando:

image

Agora você tem um servidor MCP remoto implantado!

Controle de Acesso

Este servidor MCP usa OAuth do GitHub para autenticação. Todos os usuários GitHub autenticados podem acessar ferramentas básicas como "add" e "userInfoOctokit".

A ferramenta "generateImage" é restrita a usuários GitHub específicos listados na configuração ALLOWED_USERNAMES:

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

Acesse o servidor MCP remoto pelo Claude Desktop

Abra o Claude Desktop e navegue até Configurações -> Desenvolvedor -> Editar Configuração. Isso abre o arquivo de configuração que controla quais servidores MCP o Claude pode acessar.

Substitua o conteúdo pela seguinte configuração. Após reiniciar o Claude Desktop, uma janela do navegador abrirá mostrando sua página de login OAuth. Complete o fluxo de autenticação para conceder ao Claude acesso ao seu servidor MCP. Depois de conceder o acesso, as ferramentas ficarão disponíveis para uso.

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

Quando as Ferramentas (em 🔨) aparecerem na interface, você pode pedir ao Claude para usá-las. Por exemplo: "Você poderia usar a ferramenta de matemática para somar 23 e 19?". O Claude deve invocar a ferramenta e mostrar o resultado gerado pelo servidor MCP.

Para Desenvolvimento Local

Se você quiser iterar e testar seu servidor MCP, pode fazê-lo em desenvolvimento local. Isso exigirá que você crie outro Aplicativo OAuth no GitHub:

  • Para a URL da página inicial, especifique http://localhost:8788
  • Para a URL de callback de autorização, especifique http://localhost:8788/callback
  • Anote seu Client ID e gere um Client secret.
  • Crie um arquivo .dev.vars na raiz do seu projeto com:
GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret

Desenvolva e Teste

Execute o servidor localmente para disponibilizá-lo em http://localhost:8788 wrangler dev

Para testar o servidor local, digite http://localhost:8788/sse no Inspector e clique em conectar. Depois de seguir as instruções, você poderá "Listar Ferramentas".

Usando Claude e outros Clientes MCP

Ao usar o Claude para conectar ao seu servidor MCP remoto, você pode ver algumas mensagens de erro. Isso ocorre porque o Claude Desktop ainda não suporta servidores MCP remotos, então às vezes ele fica confuso. Para verificar se o servidor MCP está conectado, passe o mouse sobre o ícone 🔨 no canto inferior direito da interface do Claude. Você deve ver suas ferramentas disponíveis lá.

Usando Cursor e outros Clientes MCP

Para conectar o Cursor ao seu servidor MCP, escolha Type: "Comando" e no campo Command, combine os campos de comando e argumentos em um só (ex.: npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse).

Observe que, embora o Cursor suporte servidores HTTP+SSE, ele não suporta autenticação, então você ainda precisa usar mcp-remote (e usar um servidor STDIO, não um HTTP).

Você pode conectar seu servidor MCP a outros clientes MCP como o Windsurf abrindo o arquivo de configuração do cliente, adicionando o mesmo JSON usado na configuração do Claude e reiniciando o cliente MCP.

Como funciona?

Provedor OAuth

A biblioteca Provedor OAuth serve como uma implementação completa de servidor OAuth 2.1 para Cloudflare Workers. Ela lida com as complexidades do fluxo OAuth, incluindo emissão, validação e gerenciamento de tokens. Neste projeto, ela desempenha o papel duplo de:

  • Autenticar clientes MCP que se conectam ao seu servidor
  • Gerenciar a conexão com os serviços OAuth do GitHub
  • Armazenar com segurança tokens e estado de autenticação no armazenamento KV

Durable MCP

O Durable MCP estende a funcionalidade base do MCP com os Durable Objects da Cloudflare, fornecendo:

  • Gerenciamento de estado persistente para seu servidor MCP
  • Armazenamento seguro do contexto de autenticação entre requisições
  • Acesso a informações do usuário autenticado via this.props
  • Suporte para disponibilidade condicional de ferramentas com base na identidade do usuário

MCP Remoto

A biblioteca MCP Remoto permite que seu servidor exponha ferramentas que podem ser invocadas por clientes MCP como o Inspector. Ela:

  • Define o protocolo de comunicação entre clientes e seu servidor
  • Fornece uma maneira estruturada de definir ferramentas
  • Lida com a serialização e desserialização de requisições e respostas
  • Mantém a conexão Server-Sent Events (SSE) entre clientes e seu servidor