Model Context Protocol (MCP) Server + Github OAuth

Это сервер Model Context Protocol (MCP) с поддержкой удалённых MCP-подключений и встроенной авторизацией Github OAuth.

Вы можете развернуть его в собственном аккаунте Cloudflare, и после того как вы создадите своё OAuth-приложение Github, у вас будет полнофункциональный удалённый MCP-сервер, на базе которого можно работать дальше. Пользователи смогут подключаться к вашему MCP-серверу, войдя в свой аккаунт GitHub.

Этот проект можно использовать как справочный пример интеграции других OAuth-провайдеров с MCP-сервером, развёрнутым на Cloudflare, с помощью библиотеки workers-oauth-provider.

MCP-сервер (работает на базе Cloudflare Workers):

• Выступает в роли OAuth сервера для ваших MCP-клиентов

• Выступает в роли OAuth клиента для вашего настоящего OAuth-сервера (в данном случае GitHub)

[!WARNING] Это демонстрационный шаблон, созданный для быстрого старта. Хотя мы реализовали несколько мер защиты, перед развёртыванием в продакшене вы должны реализовать все превентивные и эшелонированные меры безопасности. Пожалуйста, ознакомьтесь с нашим подробным руководством по безопасности: Securing MCP Servers

Начало работы

Клонируйте репозиторий и установите зависимости: 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 и нажмите connect. После прохождения процедуры аутентификации вы увидите работающие инструменты:

Теперь у вас развёрнут удалённый MCP-сервер!

Контроль доступа

Этот MCP-сервер использует GitHub OAuth для аутентификации. Все прошедшие аутентификацию пользователи GitHub могут использовать базовые инструменты, такие как "add" и "userInfoOctokit".

Инструмент "generateImage" доступен только конкретным пользователям GitHub, перечисленным в конфигурации ALLOWED_USERNAMES:

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

Подключение к удалённому MCP-серверу из Claude Desktop

Откройте Claude Desktop и перейдите в Settings -> Developer -> Edit Config. Откроется файл конфигурации, который определяет, к каким MCP-серверам Claude может получать доступ.

Замените содержимое файла приведённой ниже конфигурацией. После перезапуска Claude Desktop откроется окно браузера со страницей входа OAuth. Пройдите процедуру аутентификации, чтобы предоставить Claude доступ к вашему MCP-серверу. После этого инструменты станут доступны для использования.

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

Когда инструменты (в разделе 🔨) появятся в интерфейсе, вы можете попросить Claude использовать их. Например: «Не могли бы вы с помощью математического инструмента сложить 23 и 19?». Claude должен вызвать инструмент и показать результат, полученный от MCP-сервера.

Для локальной разработки

Если вы хотите итерироваться и тестировать свой MCP-сервер, это можно делать в локальной разработке. Для этого потребуется создать ещё одно OAuth-приложение на GitHub:

• Для 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

Чтобы протестировать локальный сервер, введите http://localhost:8788/sse в Inspector и нажмите connect. После прохождения всех шагов вы сможете выполнить "List Tools".

Использование 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 (использовать STDIO-сервер, а не HTTP-сервер).

Вы можете подключить свой MCP-сервер к другим MCP-клиентам, таким как Windsurf: откройте файл конфигурации клиента, добавьте тот же JSON, который использовался для настройки Claude, и перезапустите MCP-клиент.

Как это работает?

OAuth Provider

Библиотека OAuth Provider представляет собой полноценную реализацию OAuth 2.1-сервера для Cloudflare Workers. Она берёт на себя все сложности OAuth-процесса, включая выпуск, проверку и управление токенами. В этом проекте она выполняет двойную роль:

• Аутентификация MCP-клиентов, подключающихся к вашему серверу

• Управление подключением к OAuth-сервисам GitHub

• Безопасное хранение токенов и состояния аутентификации в KV-хранилище

Durable MCP

Durable MCP расширяет базовую функциональность MCP с помощью Durable Objects от Cloudflare и предоставляет:

• Постоянное управление состоянием для вашего MCP-сервера

• Безопасное хранение контекста аутентификации между запросами

• Доступ к данным аутентифицированного пользователя через this.props

• Условную доступность инструментов в зависимости от пользователя

MCP Remote

Библиотека MCP Remote позволяет вашему серверу предоставлять инструменты, которые могут вызывать MCP-клиенты, например, Inspector. Она:

• Определяет протокол обмена данными между клиентами и вашим сервером

• Предоставляет структурированный способ определения инструментов

• Обрабатывает сериализацию и десериализацию запросов и ответов

• Поддерживает соединение Server-Sent Events (SSE) между клиентами и вашим сервером