Как развернуть GitHub MCP Server: кроссплатформенное руководство для Windows, Linux и macOS

GitHub MCP Server — официально поддерживаемый GitHub Model Context Protocol сервер, который позволяет AI-хостам вроде Cursor, Claude Desktop, VS Code Copilot вызывать GitHub REST / GraphQL API через стандартизированные инструменты — просматривать репозитории, читать Issue, открывать PR, искать код, не копируя вывод команд gh в чат снова и снова.

В этой статье по порядку «сначала выбор способа развёртывания, затем настройка окружения, в конце подключение IDE» рассмотрены три пути установки для Windows, Linux и macOS, а также готовые к копированию фрагменты конфигурации и чеклист по устранению неполадок.

С апреля 2025 года ранний npm-пакет сообщества @modelcontextprotocol/server-github устарел; единственный официально поддерживаемый локальный образ сейчас — ghcr.io/github/github-mcp-server, удалённая конечная точка — https://api.githubcopilot.com/mcp/.

Как выбрать способ развёртывания

Перед установкой ПО сверьтесь с таблицей ниже и определите, какой путь вам подходит:

Для всех трёх способов логика аутентификации одинакова: либо настраивается Personal Access Token (PAT), либо в локальном режиме Docker / бинарника используется OAuth-вход через браузер (токен хранится только в памяти, на диск не записывается).

Общая подготовка

Независимо от выбранного пути рекомендуется выполнить четыре шага:

1. Создать GitHub PAT
   Откройте страницу создания Fine-grained PAT и отметьте нужные разрешения. Для чтения репозиториев обычно достаточно Contents: Read, Metadata: Read; для создания PR / Issue добавьте права на запись.

2. Проверить версию хоста
   - Cursor: удалённый Streamable HTTP поддерживается с v0.48.0+
   - Claude Desktop / VS Code: см. документацию MCP для каждого продукта

3. (Схема с локальным Docker) Установить и запустить Docker
   - Windows / macOS: Docker Desktop
   - Linux: Docker Engine + добавление текущего пользователя в группу docker

4. Предварительно скачать образ (необязательно, но рекомендуется)

docker pull ghcr.io/github/github-mcp-server

Если при скачивании появляется unauthorized, выполните docker logout ghcr.io и повторите попытку — иногда мешает устаревшая сессия входа в ghcr.

Способ 1: удалённый хостинг (самый простой)

GitHub предоставляет управляемую MCP-конечную точку по адресу https://api.githubcopilot.com/mcp/ — Docker на машине не нужен. Подходит для Linux-серверов, лёгких сред Windows или когда политика компании запрещает контейнеры.

Пример конфигурации Cursor

Отредактируйте глобальный конфиг ~/.cursor/mcp.json (в Windows путь %USERPROFILE%\.cursor\mcp.json):

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

Замените YOUR_GITHUB_PAT на реальный токен, сохраните и полностью перезапустите Cursor. В Settings → Tools & Integrations → MCP Tools должен появиться зелёный индикатор онлайн; в Composer спросите «перечисли мои репозитории GitHub» для проверки.

Важные замечания

• В удалённом режиме в основном используется аутентификация по PAT; поддержка OAuth у части хостов ещё дорабатывается.
• Корпоративный прокси / файрвол должен пропускать исходящий HTTPS к api.githubcopilot.com.
• Не добавляйте PAT в репозиторий; при проектном .cursor/mcp.json включите его в .gitignore.

Способ 2: локальное развёртывание в Docker (рекомендуется официально)

Схема Docker общается с хостом через stdio: хост запускает docker run -i ..., процесс в контейнере читает и пишет стандартный ввод/вывод. Это команда по умолчанию за кнопкой быстрой установки в Claude Desktop, Windsurf и Cursor.

Установка на macOS

1. Установите Docker Desktop for Mac (для Apple Silicon — версию ARM64).
2. В строке меню значок кита должен показывать Running.
3. Проверка в терминале:

docker run --rm ghcr.io/github/github-mcp-server --help

4. Запишите в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Установка на Linux

1. Установите Docker Engine по дистрибутиву (пример Ubuntu: sudo apt install docker.io).
2. Добавьте пользователя в группу docker, чтобы не вводить sudo каждый раз:

sudo usermod -aG docker "$USER"
newgrp docker

3. Убедитесь, что демон Docker запущен: sudo systemctl enable --now docker.
4. Конфигурация MCP полностью совпадает с macOS — путь ~/.cursor/mcp.json тот же.

На Linux-сервере без графического интерфейса, если не хотите хранить PAT в открытом виде в конфиге, можно передать его через переменную окружения:

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"

Затем в блоке env файла mcp.json укажите ту же переменную (часть хостов поддерживает синтаксис ${env:GITHUB_PERSONAL_ACCESS_TOKEN} — см. их документацию).

Установка на Windows

1. Установите Docker Desktop for Windows.
   - Рекомендуется бэкенд WSL 2 (Settings → General → Use WSL 2 based engine).
2. Убедитесь, что значок Docker Desktop в трее показывает работу.
3. Путь к конфигу: %USERPROFILE%\.cursor\mcp.json.
4. Содержимое JSON как на macOS; command по-прежнему docker (Docker Desktop добавляет CLI в PATH).

Частая ловушка в Windows: в WSL docker может работать, но Cursor на Windows читает mcp.json со стороны Windows — не смешивайте конфиги. Если Cursor установлен в Windows, а проект в WSL, настраивайте MCP в каталоге пользователя Windows.

Вход через OAuth (без ручного ввода PAT)

Официальный образ содержит учётные данные OAuth-приложения. В режиме Docker нужно пробросить порт обратного вызова на loopback:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "127.0.0.1:8085:8085",
        "-e", "GITHUB_OAUTH_CALLBACK_PORT",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_OAUTH_CALLBACK_PORT": "8085"
      }
    }
  }
}

При первом подключении откроется браузер для входа в GitHub; токен хранится в памяти и исчезает при остановке контейнера. На headless-сервере см. в официальной документации запасной сценарий device code.

Способ 3: сборка из исходников Go (без Docker)

Подходит, когда Docker установить нельзя или нужно ограничить toolset (открыть только часть возможностей API).

Общие шаги для всех платформ

Предварительно: установите Go 1.24+.

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
go build -o github-mcp-server cmd/github-mcp-server/main.go

Имя бинарника можно выбрать своё; ниже используется ./github-mcp-server.

Запуск с PAT (режим stdio):

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
./github-mcp-server stdio

Подключение локального бинарника в Cursor:

{
  "mcpServers": {
    "github": {
      "command": "/绝对路径/github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Для обновления достаточно git pull && go build; ждать релиза Docker-образа не нужно.

Подключение других IDE и CLI

Имена ключей конфигурации зависят от хоста, но ядро команды Docker одинаково:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

• Claude Desktop: блок mcpServers в claude_desktop_config.json, структура как у Cursor.
• VS Code Copilot: поддерживаются удалённый и локальный режимы; локально тоже рекомендуется Docker-образ.
• Claude Code CLI: чаще выбирают лёгкий бинарник, чтобы снизить накладные расходы контейнера.

Полные примеры для каждого хоста — в каталоге docs/installation-guides/ официального репозитория.

Рекомендации по безопасности и эксплуатации

1. PAT с минимальными правами: выдавайте разрешения под toolset, регулярно ротируйте.
2. Права на конфиг: chmod 600 ~/.cursor/mcp.json (Linux / macOS).
3. Режим только чтения: параметры запуска могут включить read-only, чтобы AI не менял репозиторий по ошибке.
4. Корпоративный GitHub Enterprise Server: нужны собственные OAuth App / GitHub App, учётные данные github.com по умолчанию не подходят — см. официальный docs/oauth-login.md.

Дополнения по различиям платформ

Пути и переменные окружения

~/.cursor/mcp.json

Глобальная конфигурация MCP в macOS и Linux; в Windows — %USERPROFILE%\.cursor\mcp.json.

GITHUB_PERSONAL_ACCESS_TOKEN

Имя переменной окружения для PAT в режиме Docker / бинарника; после установки имеет приоритет над OAuth.

GITHUB_OAUTH_CALLBACK_PORT

Порт прослушивания OAuth-обратного вызова в браузере; в Docker обычно фиксируют 8085.

Горячие клавиши и привычные приёмы

В Cursor Composer можно нажать Cmd+Shift+P (в Windows — Ctrl+Shift+P), открыть палитру команд и найти настройки MCP. Раньше некоторые запускали сервис одной строкой npx @modelcontextprotocol/server-github — этот способ устарел, используйте Docker или удалённую конечную точку из этой статьи.

В продакшене обязательно храните PAT в переменных окружения или менеджере секретов, не в файлах проекта, которые отслеживает git.

Чеклист проверки (перед публикацией)

1. Зелёная точка на панели MCP
2. В списке инструментов есть пункты с префиксом github_*
3. Успешный вызов операции только для чтения (например, список репозиториев)

Где смотреть логи

Логи Cursor: Help → Toggle Developer Tools → Console, фильтр по ключевому слову MCP; путь к логам Claude Desktop зависит от платформы — полный список в разделе troubleshooting официальной документации.

Быстрая диагностика неполадок

Быстрая самопроверка: вручную выполните Docker-команду в терминале и посмотрите, не появляется ли ошибка в stderr сразу; сравните с командой запуска MCP в логах IDE.

Итог

• Нужно быстрее всего: удалённый https://api.githubcopilot.com/mcp/ + PAT, в Cursor v0.48+ укажите url.
• Нужна стабильность и воспроизводимость: на всех платформах одинаково docker run -i --rm ... ghcr.io/github/github-mcp-server.
• Нужна минимальная нагрузка или кастомизация: go build бинарника, подключение через stdio.

После развёртывания настоящая экономия времени MCP — в диалоге с AI на естественном языке: например, «сделай краткое резюме 5 последних открытых issue в репозитории kvmkit». Если вы параллельно настраиваете CI/CD-конвейер или нужен облачный Mac для сборок 24/7, MCP для разработки и автоматизацию релизов можно встроить в одну цепочку инструментов.

Частые вопросы