[[AI|Назад]] <br> > Страница доступна по альтернативной ссылке: https://bekhan.org/how-connect-local-mcp-to-ai-client > Материал, который вы сейчас читаете, является [[Типы материалов на сайте|статьей]]. > Инструкция написана 01.09.2025 <br> Данная инструкция показывает как полностью с нуля добавить сторонний локальный [[Что такое MCP-сервер?|MCP-сервер]] в [[Что такое ИИ-клиент?|ИИ-клиент]] на `MacOS`. Инструкция составлена на примере подключения локальных MCP-серверов к ИИ-плагину в `IDE Rider`, но в целом она применима к любым ИИ-клиентам, которые используются на `MacOS`. В качестве MCP-сервера был взят [Context7](https://github.com/upstash/context7). В качестве ИИ-клиентов были взяты `Rider`-плагины: Github Copilot, Claude Code, Junie. ### 1. Смена оболочки в macOS-терминале > **Зачем менять оболочку?** > В данной инструкции команды расписаны с расчётом на то, что будет использоваться (или уже используется) оболочка `zsh`. Apple [[Почему Apple рекомендует Zsh|рекомендует]] использовать `zsh` вместо `bash` по умолчанию, и поэтому если у вас используется оболочка `bash`, то вы увидите предупреждение в терминале: ``` The default interactive shell is now zsh. To update your account to use zsh, please run `chsh -s /bin/zsh`. For more details, please visit https://support.apple.com/kb/HT208050. --- Суть предупреждения: «системная дефолтная интерактивная оболочка macOS теперь — zsh, а у Вашего пользователя всё ещё bash» ``` --- Проверяем, какая текущая оболочка в терминале macOS: ```zsh echo $SHELL ``` > Если команда выше показала, что в терминале macOS оболочка `zsh`, то пропускаем данный шаг (шаг 1) и переходим к шагу 2 --- Если команда выше показала, что в терминале macOS оболочка bash, то выполняем в терминале команду: ```zsh chsh -s /bin/zsh ``` --- Закройте и откройте терминал macOS и снова пропишите команду, чтобы убедиться, что оболочка сменилась на `zsh`. ```zsh echo $SHELL ``` --- ### 2. Смена оболочки в терминале Rider > **Переходите сразу к шагу 3, если выполняется любое из условий:** > - Вы не используете Rider или другую IDE > - Ваша IDE не имеет встроенного терминала > - В вашем ИИ-клиенте нет собственного терминала В данном шаге мы будем приводить окружения `Rider`-терминала к окружению `MacOS`-терминала и оболочке `zsh`, если этого ещё не было сделано. > **Зачем менять оболочку?** > Важно, чтобы `Rider`-терминал и ваш системный `Terminal` использовали одинаковую схему загрузки окружения → один и тот же `PATH`, одни и те же переменные. --- В настройках IDE Rider (Rider → Settings → Tools → Terminal → Shell path) укажите путь: ``` /bin/zsh -l ``` Поскольку терминал Rider работает в интерактивном режиме (псевдотерминал, PTY), `zsh` работает как интерактивная оболочка. Если указать `/bin/zsh -l`, она дополнительно станет _login_-шеллом, поэтому конфиги загружаются так: `~/.zshenv`, затем `~/.zprofile` (login), потом `~/.zshrc` (interactive) и в конце `~/.zlogin` (login-post). - Если запустить `/bin/zsh` без ключа `-l` (login shell), то загружаются только `~/.zshenv` и `~/.zshrc`, но пропускаются `~/.zprofile` и `~/.zlogin`. - [[Почему разработчики Rider НЕ добавили ключ -l в настройке Shell Path?]] --- > **Важно!** После изменения настроек терминала в `Rider` рекомендую на всякий перезапустить `IDE` для корректного применения изменений. Закройте и откройте `Rider`-терминал и пропишите в нем команду, чтобы убедиться, что оболочка сменилась на `zsh`. ```zsh echo $SHELL ``` --- ### 3. Проверяем, что Homebrew уже установлен Убеждаемся, что `Homebrew` уже установлен, прежде чем переходить к следующим шагам. Команды вводим через `MacOS`-терминал. > **Зачем нужен Homebrew?** > `Homebrew` — это пакетный менеджер для macOS, который понадобится для установки `nvm` и других необходимых инструментов. Он упрощает установку и управление программным обеспечением из командной строки. --- Если команда вернёт версию — `Homebrew` работает и можно продолжать. Если команда не найдена — нужно сначала [[Установка Homebrew на macOS|установить]] `Homebrew` ```zsh brew --version ``` --- ### 4. Ставим nvm и Node LTS > **Зачем ставим?** > `nvm` (`Node Version Manager`) нужен для управления версиями `Node.js`. Он позволяет легко переключаться между разными версиями `Node` для разных проектов, не затрагивая системные настройки Команды вводим через `MacOS`-терминал. --- Устанавливаем `Node Version Manager` через `Homebrew` ```zsh brew install nvm ``` --- Создаем папку `.nvm` в домашней директории для файлов `nvm`. Флаг `-p` создает папку, если её нет, и не дает ошибку, если она уже есть ```zsh mkdir -p ~/.nvm ``` --- Добавляем переменную окружения `NVM_DIR` в файл [[Файл .zshrc|.zshrc]]. Эта переменная указывает `nvm`, где находятся его собственные файлы и конфигурации. Версии `Node.js` будут храниться в подпапке `$NVM_DIR/versions/node/` ```zsh echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc ``` --- Добавляем в [[Файл .zshrc|.zshrc]] загрузку `nvm` при запуске терминала. Делаем команду `nvm` доступной в каждой новой сессии ```zsh echo 'source "$(brew --prefix nvm)/nvm.sh"' >> ~/.zshrc ``` --- Перезагружаем настройки [[Файл .zshrc|.zshrc]] в текущей сессии терминала. Применяем изменения сразу, без перезапуска терминала ```zsh source ~/.zshrc ``` --- Устанавливаем последнюю `LTS` версию `Node.js` и переключаемся на неё ```zsh nvm install --lts nvm use --lts ``` --- Проверяем версии `Node.js`, `npm` и `npx`. Каждая команда должна вернуть номер версии. Если появляется "`command not found`" — что-то пошло не так на предыдущих шагах ```zsh node -v # должно быть `LTS` версия (например `v20.x` или `v22.x`) npm -v npx -v ``` --- ### 5. Подключаем локальный сервер в ИИ-клиент [[Как в mcp.json указать несколько MCP-серверов?]] Находим у желаемого ИИ-клиента настройки подключения к `MCP`-серверу, должна быть кнопка добавления нового сервера. Должен открыться файл `mcp.json`. Его мы будем редактировать. > **Важно!** > Учитывайте, что в mcp.json можно указать mcp-сервер таким образом, что он не будет запускаться, хотя mcp-сервер был добавлен по документации ИИ-клиента. [[Интерактивный и неинтерактивный режим запуска mcp-сервера|Подробнее]] Обратите внимание, что у каких-то ИИ-клиентов в `mcp.json` используется ключевое слово `servers`, в каких-то `mcpServers`, поэтому лучше всего проверять документацию ИИ-клиента и посмотреть пример заполнения `mcp.json`. ##### Github copilot Copilot Chat → переключитесь в Agent mode. Нажмите значок инструментов внизу («Configure your MCP server») → Add MCP Tools — откроется/создастся `mcp.json`. В JetBrains поддерживаются remote серверы по `url` и local серверы через запуск команды (stdio). ([GitHub Docs](https://docs.github.com/copilot/customizing-copilot/using-model-context-protocol/extending-copilot-chat-with-mcp "Extending GitHub Copilot Chat with the Model Context Protocol (MCP) - GitHub Docs")) ```json { "servers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` ##### AI Assistant (Junie) Что я указывал для `AI Assistant (Junie)` и это работало: ```json { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } } ``` ##### Claude Code > **Важно!** > Если добавите MCP-сервер через терминал MacOS, а не через терминал Rider, то MCP-сервер может не появиться в Claude Code внутри Rider. Это происходит из-за разных областей конфигурации (scope). Рекомендуется добавлять сервер именно через терминал Rider, чтобы он корректно подключился к проекту. Открываем `Claude Code` в `Rider`-терминале и переводим его в режим `bash mode` (Просто пишем восклицательный знак) ![[img.png]] --- Пишем в Claude Code: ```zsh claude mcp add-json context7 '{"command": "npx", "args": ["-y", "@upstash/context7-mcp"]}' ``` [Claude Docs](https://docs.anthropic.com/en/docs/claude-code/mcp) --- ### 6. Убеждаемся, что MCP-сервер успешно добавлен в ИИ-клиент В интерфейсе ИИ-клиента, где добавляется новый MCP-сервер, это должно так или иначе отображаться. ##### AI Assistant (Junie) ![[Снимок экрана 2025-09-01 в 07.42.16.png]] ##### GitHub Copilot ![[Снимок экрана 2025-09-01 в 07.44.26.png]] ##### Claude Code Открываем `Claude Code` в `Rider`-терминале и переводим его в режим `bash mode` (Просто пишем восклицательный знак) ![[img.png]] Проверяем статус mcp-сервера, терминал должен ответить `MCP server is connected`. ```zsh claude mcp get context7 ``` ---- Выполните тестовую проверку: спросите в чате что-то, что вынуждает вызвать инструмент вашего сервера (например, любую простую операцию, которую ваш tool предоставляет). Успешный запуск = Copilot перечисляет вызванный tool и возвращает его результат. Это и есть конечная проверка готовности MCP. ### 7. Используем MCP-сервер при написании промпта в ИИ-клиент Предположим, что мы используем mcp-сервер `context7`. В конце промпта добавляйте «`use context7`». Также можно настроить авто-правило в некоторых клиентах, чтобы вызывать Context7 на вопросы про код/документацию. ([GitHub](https://github.com/upstash/context7 "GitHub - upstash/context7: Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors"))