github-mcp-proxy

Самохостируемый GitHub MCP-сервер, работающий на Cloudflare Workers, разработанный для личного использования или небольших команд с защитными барьерами для каждого репозитория для ИИ-агентов.

Любой агент с поддержкой MCP (Claude, Codex, ChatGPT, Cursor, Cline и др.) может быть подключен — с жестким контролем того, к каким репозиториям он имеет доступ и как именно.

[!WARNING] Если вам нужна безопасность или стабильность, используйте официальный GitHub MCP-сервер. Форкайте свободно; после форка ответственность за проблемы безопасности лежит на вас.

Зачем это нужно

Обычные токены GitHub предоставляют агенту полный доступ к учетной записи. Этот сервер ограничивает его:

• Уровни доступа для каждого репозитория — read (чтение) / issues (задачи) / full (полный)

• Защита веток — новые ветки должны соответствовать префиксу (по умолчанию claude/); ветки main/master никогда не доступны для записи

• Политика сообщений коммитов — Conventional Commits, проверяемые на стороне сервера

• Белый список меток — allowedLabels для каждого репозитория; сервер никогда не создает метки на GitHub автоматически

• Запрещенные пути — .github/workflows/** всегда заблокированы

• Аудит действий — каждая запись автоматически добавляет трейлеры Signed-off-by / Assisted-by или футер, идентифицирующий агента и модель

Related MCP server: Kontrol

Архитектура

 MCP agent ──(Streamable HTTP + OAuth)──▶ Cloudflare Worker
                                              │
                                              ├── workers-oauth-provider  (OAuth 2.1 server to MCP clients)
                                              ├── GitHub OAuth            (OAuth client to github.com)
                                              ├── KV                      (session tokens)
                                              ├── Durable Object          (MCP agent state)
                                              └── Octokit                 (GitHub REST)

Конфигурация (ghmcp.config.ts) упаковывается вместе с Worker во время развертывания — никаких чтений из KV во время выполнения, проверка типов через satisfies.

Быстрый старт

git clone <your-fork>
cd kz-github-mcp
npm install
cp ghmcp.config.sample.ts ghmcp.config.ts   # edit: repos you want to expose
cp wrangler.sample.jsonc wrangler.jsonc      # edit: KV id + worker name
cp .env.example .env                         # edit: for local dev only

Создайте GitHub OAuth App (Homepage = https://<worker>.<subdomain>.workers.dev, Callback = /callback), затем:

wrangler kv namespace create "OAUTH_KV"      # add the id to wrangler.jsonc
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY    # openssl rand -hex 32
npm run deploy

Локальная разработка: тот же процесс со вторым OAuth-приложением, указывающим на http://localhost:8788, учетные данные в .env, затем npm run dev.

Непрерывное развертывание (опционально)

.github/workflows/deploy.yml развертывает проект в Cloudflare при каждом пуше в main. Установите два секрета репозитория в GitHub Settings → Secrets and variables → Actions:

Учетные данные GitHub OAuth (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY) хранятся как секреты Wrangler на самом Worker, а не в GitHub Actions — вам нужно установить их только один раз с помощью wrangler secret put.

См. docs/ARCHITECTURE.md для понимания принципов работы и docs/CONFIG.md для описания всех полей конфигурации.

Подключение ИИ-агента

Claude (claude.ai) — Settings → Connectors → Add custom connector → вставьте https://<worker>.<subdomain>.workers.dev/sse.

Claude Code / Codex / Cursor / Cline — добавьте в MCP-конфигурацию клиента:

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

Любой MCP-хост — укажите тот же эндпоинт /sse. OAuth-процесс запустится при первом подключении.

Чтобы научить агента правильно использовать инструменты, включите SKILL.md в его системный промпт / инструкции проекта / директорию навыков.

Инструменты

Имеют префикс ghmcp_. Каждый объявляет минимальный уровень доступа; сервер отклоняет вызовы, если уровень ниже требуемого.

Любой инструмент можно отключить через disabledTools в конфигурации.

Валидация

npm run validate-config

Использует CLI gh для подтверждения того, что каждый репозиторий в ghmcp.config.ts существует и что каждая метка в allowedLabels присутствует на GitHub. Запускается автоматически как хук prebuild, поэтому опечатка приведет к ошибке npm run build.

Лицензия

Изначально форкнуто из cloudflare/ai/demos/remote-mcp-github-oauth. Лицензия MIT.

Этот инструмент распространяется по лицензии MIT — см. LICENSE.