MCP для LM Studio — полная инструкция развёртывания (Mac + Windows)

Принцип работы MCP в LM Studio

MCP-сервер — обычный консольный процесс (Node или Python), который LM Studio запускает как дочерний и общается с ним JSON-RPC через stdin/stdout. Конфигурация — один файл mcp.json в корне профиля LM Studio. Папки в extensions/plugins/mcp/ генерируются из него автоматически — руками не править.

Главные грабли на обеих ОС: GUI-приложение запускается с урезанным PATH и не видит npx/uvx. Лечение всегда одно — абсолютные пути к бинарям в mcp.json.

macOS — установка и настройка MCP в LM Studio

Необходимые Зависимости

# Node.js (для npx-серверов) — если нет:
brew install node

# uv (для uvx-серверов):\

brew install uv # pandoc + TeX (для docx/pdf): brew install pandoc texlive

Проверка и запись путей (понадобятся в конфиге):

which npx uvx pandoc xelatex
# типично: npx→/opt/homebrew/bin, uvx→~/.local/bin (!), pandoc/xelatex→/opt/homebrew/bin

ВАЖНО: brew-установка uv кладёт uvx в ~/.local/bin/uvx, НЕ в /opt/homebrew/bin. Всегда проверять which uvx, не предполагать.

Прогрев uvx-серверов (разово, из терминала)

uvx excel-mcp-server==0.1.8 stdio   # скачает Python+пакеты; повисла молча = ОК; Ctrl+C
uvx mcp-pandoc                       # то же самое

Defaults-файл для кириллицы в PDF

bash 

mkdir -p ~/.pandoc && cat > ~/.pandoc/ru-pdf.yaml <<‘EOF’
pdf-engine: xelatex
variables:
mainfont: «Helvetica»
monofont: «Menlo»
lang: ru
geometry: margin=2cm
EOF

Проверка руками (обязательно!):

printf '# Тест\n\nКириллица: жирный.\n' > /tmp/t.md
pandoc /tmp/t.md -d ~/.pandoc/ru-pdf.yaml -o ~/Downloads/t.pdf
pdftotext ~/Downloads/t.pdf - | head # русский текст должен быть виден

mcp.json — ~/.lmstudio/mcp.json

{
  "mcpServers": {
    "mac-filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
        "/Users/USERNAME/Documents", "/Users/USERNAME/Downloads", "/Users/USERNAME/Desktop"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "ВАШ_КЛЮЧ" }
    },
    "excel": {
      "command": "/Users/USERNAME/.local/bin/uvx",
      "args": ["excel-mcp-server==0.1.8", "stdio"]
    },
    "pandoc": {
      "command": "/Users/USERNAME/.local/bin/uvx",
      "args": ["mcp-pandoc"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin" }
    }
  }
}

Заменить USERNAME. Блок env.PATH у pandoc обязателен — сервер должен найти бинарь pandoc и xelatex, которых GUI-процесс в PATH не имеет.

Windows установка и настройка MCP в LM Studio

Для настройки mcp в LM Studio устанавливаем зависимости через (PowerShell)

winget install OpenJS.NodeJS.LTS
winget install astral-sh.uv
winget install JohnMacFarlane.Pandoc
winget install MiKTeX.MiKTeX

ПОСЛЕ установки: закрыть и открыть PowerShell заново (PATH обновляется только в новых процессах). Проверить и записать пути:

where.exe npx # типично: C:\Program Files\nodejs\npx.cmd
where.exe uvx # типично: C:\Users\ИМЯ\AppData\Local\Microsoft\WinGet\Links\uvx.exe
where.exe pandoc
where.exe xelatex

MiKTeX Console → Settings → «Install missing packages on-the-fly» → Yes. Иначе первый PDF молча зависнет на невидимом диалоге установки пакетов.

Прогрев uvx-серверов

uvx excel-mcp-server==0.1.8 stdio # Installed N packages → тишина = ОК → Ctrl+C
uvx mcp-pandoc

Defaults-файл для кириллицы

Создать C:\Users\ИМЯ\.pandoc\ru-pdf.yaml:

pdf-engine: xelatex
variables:
  mainfont: "Arial"
  monofont: "Consolas"
  lang: ru
  geometry: margin=2cm

Проверка руками:

"# Тест`n`nКириллица: **жирный**." | Out-File -Encoding utf8 $env:TEMP\t.md
pandoc $env:TEMP\t.md -d $env:USERPROFILE\.pandoc\ru-pdf.yaml -o $env:USERPROFILE\Downloads\t.pdf
# открыть PDF глазами: русский текст должен быть

mcp.json — C:\Users\ИМЯ\.lmstudio\mcp.json

{
  "mcpServers": {
    "win-filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\ИМЯ\\Documents", "C:\\Users\\ИМЯ\\Downloads", "C:\\Users\\ИМЯ\\Desktop"]
    },
    "brave-search": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "ВАШ_КЛЮЧ" }
    },
    "excel": {
      "command": "C:\\Users\\ИМЯ\\AppData\\Local\\Microsoft\\WinGet\\Links\\uvx.exe",
      "args": ["excel-mcp-server==0.1.8", "stdio"]
    },
    "pandoc": {
      "command": "C:\\Users\\ИМЯ\\AppData\\Local\\Microsoft\\WinGet\\Links\\uvx.exe",
      "args": ["mcp-pandoc"]
    }
  }
}

Особенности Windows:

• • слэши в JSON удваивать: C:\\Users\\...;

• • npx запускать через cmd /c (это .cmd-обёртка, напрямую может не спавниться);

• • путь uvx от winget — в WinGet\Links, НЕ в .local\bin;

• • символы < > в путях недопустимы — ошибка «Синтаксическая ошибка в имени файла» в логе (в кракозябрах CP866) означает, что в конфиге остался плейсхолдер.

Перезапуск LM Studio

Полностью выйти из LM Studio (включая трей) и открыть заново. Save в редакторе НЕ обновит PATH работающего процесса.

Системный промпт модели в LM Studio (обе ОС)

Вставить в System Prompt, сохранить как пресет. Пути подставить под ОС.

Ты работаешь с MCP-инструментами. Правила выбора инструмента:

ФАЙЛЫ
— Текстовые (.md .txt .sh .py .json .csv): filesystem → write_file.
— Таблицы (.xlsx): ТОЛЬКО инструменты excel. Код в песочнице записать файл не может.
— Документы (.docx .pdf .html .epub): pandoc → convert-contents.
Сначала написать .md через filesystem, затем конвертировать.

КРИТИЧНО: PDF С РУССКИМ ТЕКСТОМ
Всегда передавать: defaults_file: <ПУТЬ>/.pandoc/ru-pdf.yaml
Без него кириллица МОЛЧА исчезает из PDF (файл создаётся, ошибок нет).
Для .docx defaults_file не нужен.

ЧЕСТНОСТЬ ОБ ОШИБКАХ
Нет инструмента в списке — так и сказать. НЕ выдумывать «ограничения
безопасности». Инструмент вернул ошибку — процитировать её текст.

Проверка после развёртывания mcp (чек-лист)

1. 1. Лог LM Studio: каждый [Plugin(mcp/ИМЯ)] даёт «Register with LM Studio», БЕЗ строк stderr про ENOENT / «не является командой» / «синтаксическая ошибка».

1. 1. Тумблеры серверов в панели инструментов включены.

1. 1. Тест filesystem: «создай файл test.md в Downloads с текстом привет».

1. 1. Тест excel: «создай test.xlsx в Downloads, лист Data, A1=123».

1. 1. Тест pandoc+кириллица: «напиши абзац по-русски в md, сконвертируй в PDF с defaults_file, сохрани в Downloads» → открыть PDF глазами.

Диагностика, если mcp сервер в LM Studio «не работает»

НЕ верить объяснениям модели («MCP не разрешает», «нет прав») — это конфабуляция при отсутствии инструмента в списке. Проверять слоями:

1. 1. Лог LM Studio: стартовал ли плагин? stderr?

1. 1. Команду из mcp.json выполнить руками в терминале — запускается ли вообще?

1. 1. Пути: which uvx / where.exe uvx — совпадает ли с конфигом?

1. 1. Процесс: ps aux | grep excel-mcp / Task Manager — жив ли после старта?

1. 1. Кракозябры в Windows-логе = CP866; «not found»-классы ошибок означают ПУТЬ.

Обновление пинов (раз в квартал)

curl -s https://pypi.org/pypi/excel-mcp-server/json | jq -r .info.version
# новее 0.1.8? → посмотреть releases на github.com/haris-musa/excel-mcp-server
# → поменять ==X.Y.Z в mcp.json на обеих машинах → дымовой тест

npx-серверы (@modelcontextprotocol/*) не пинованы (официальные, риск ниже); при желании пиновать так же: @modelcontextprotocol/server-filesystem@X.Y.Z.

Известные грабли (сводка)