MCP-сервер BookStack

Сервер Model Context Protocol (MCP), который предоставляет ИИ-ассистентам полный доступ к вашей документации BookStack — поиск, чтение, создание и управление контентом.

npx bookstack-mcp

Возможности

• 20 инструментов только для чтения + 18 инструментов для записи для полного покрытия API BookStack

• Книги, главы, страницы, полки, вложения и комментарии — полный CRUD

• Поддержка корзины — восстановление или окончательное удаление контента, помеченного как удаленный

• Типобезопасная проверка входных данных с помощью Zod (автоматическое приведение параметров string/number для широкой совместимости с клиентами)

• Встроенные URL-адреса и предварительный просмотр контента во всех ответах

• Резервный экспорт в Markdown для страниц, созданных в HTML, чтобы ИИ-клиенты всегда получали полезный контент

• Операции записи по умолчанию отключены для безопасности

• Работает с Claude Desktop, Claude Code, LibreChat и любым MCP-совместимым клиентом

• Транспорты Stdio и Streamable HTTP

Related MCP server: PDF RAG MCP Server

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

Установка из npm

npx bookstack-mcp

Или клонирование и сборка

git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp
npm install && npm run build
npm start

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

BOOKSTACK_BASE_URL=https://your-bookstack.com   # Required
BOOKSTACK_TOKEN_ID=your-token-id                # Required
BOOKSTACK_TOKEN_SECRET=your-token-secret        # Required
BOOKSTACK_ENABLE_WRITE=false                    # Optional, default false
BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=false        # Optional, default false

Предупреждение о безопасности: BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=true отключает проверку TLS-сертификатов для исходящих запросов к BookStack. Используйте только для самоподписанных сертификатов в доверенной локальной сети — соединения становятся уязвимыми для атак типа MITM. Сервер записывает строку WARNING в лог при запуске, если эта опция включена.

Настройка клиента

Claude Desktop

Добавьте в конфигурацию Claude Desktop:

{
  "mcpServers": {
    "bookstack": {
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
        "BOOKSTACK_TOKEN_ID": "your-token-id",
        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

LibreChat (stdio, для одного пользователя)

Добавьте в ваш librechat.yaml:

mcpServers:
  bookstack:
    command: npx
    args:
      - -y
      - bookstack-mcp
    env:
      BOOKSTACK_BASE_URL: "https://your-bookstack.com"
      BOOKSTACK_TOKEN_ID: "your-token-id"
      BOOKSTACK_TOKEN_SECRET: "your-token-secret"

LibreChat (Streamable HTTP, рекомендуется для продакшена / Docker)

Запустите сервер как долгоживущий HTTP-сервис и укажите LibreChat URL. Это правильная настройка для многопользовательских или контейнеризированных развертываний.

Запустите сервер в режиме HTTP:

MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
BOOKSTACK_BASE_URL=https://your-bookstack.com \
BOOKSTACK_TOKEN_ID=your-token-id \
BOOKSTACK_TOKEN_SECRET=your-token-secret \
npx bookstack-mcp

Затем настройте LibreChat:

mcpServers:
  bookstack:
    type: streamable-http
    url: http://bookstack-mcp:8080/mcp

Критическое изменение в версии 3.0.0: устаревший транспорт HTTP+SSE (GET /sse + POST /messages) был удален. Streamable HTTP по адресу /mcp уже поддерживает SSE для потоковых ответов и является единственным HTTP-транспортом в текущих MCP-клиентах. Если вы используете старый клиент, которому нужны устаревшие эндпоинты, зафиксируйте версию bookstack-mcp@2.x.

Переменные окружения для HTTP-транспорта

При привязке к 0.0.0.0 (например, внутри контейнера, доступного из других сервисов), установите MCP_HTTP_ALLOWED_HOSTS в имена хостов, которые LibreChat будет использовать для доступа к этому серверу, например MCP_HTTP_ALLOWED_HOSTS=bookstack-mcp,bookstack-mcp.internal.

Перезапустите LibreChat после изменения конфигурации.

Claude Code (CLI)

Рекомендуемый путь — маркетплейс ttpears/claude-plugins, который поставляет манифест плагина этого репозитория (.claude-plugin/plugin.json):

/plugin marketplace add ttpears/claude-plugins
/plugin install bookstack-mcp@ttpears-plugins

Затем установите переменные окружения BOOKSTACK_* в вашей оболочке, чтобы MCP-сервер плагина мог пройти аутентификацию:

export BOOKSTACK_BASE_URL=https://your-bookstack.com
export BOOKSTACK_TOKEN_ID=your-token-id
export BOOKSTACK_TOKEN_SECRET=your-token-secret

Ручная установка (альтернатива)

Если вы не хотите использовать маркетплейс, зарегистрируйте сервер напрямую с помощью claude mcp add. Повторите --env для каждой переменной, поместите все флаги перед именем сервера и используйте -- для обозначения начала команды, которую запустит Claude Code:

claude mcp add bookstack \
  --transport stdio \
  --scope user \
  --env BOOKSTACK_BASE_URL=https://your-bookstack.com \
  --env BOOKSTACK_TOKEN_ID=your-token-id \
  --env BOOKSTACK_TOKEN_SECRET=your-token-secret \
  -- npx -y bookstack-mcp

Область действия (Scope) определяет, где записывается запись:

Результирующая запись конфигурации выглядит так (в .mcp.json для области проекта или ~/.claude.json в противном случае):

{
  "mcpServers": {
    "bookstack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
        "BOOKSTACK_TOKEN_ID": "your-token-id",
        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Совет для закоммиченного .mcp.json: Claude Code раскрывает ссылки ${VAR} и ${VAR:-default} в .mcp.json из окружения оболочки. Используйте это, чтобы секреты не попадали в git: установите "BOOKSTACK_TOKEN_SECRET": "${BOOKSTACK_TOKEN_SECRET}" в файле и пусть каждый разработчик экспортирует переменную в своей оболочке.

Ресурсы MCP

Книги и страницы также представлены как ресурсы MCP, поэтому клиенты, которые просматривают ресурсы (Claude Desktop, MCP Inspector и т.д.), могут упоминать их напрямую через @:

Оба шаблона поддерживают автодополнение id: при вводе сервер ищет в BookStack и возвращает соответствующие ID, чтобы вам не приходилось запоминать числовые ID вручную.

Доступные инструменты

Операции чтения (всегда доступны)

Операции записи (требуется BOOKSTACK_ENABLE_WRITE=true)

Настройка API BookStack

1. Войдите в BookStack как администратор

2. Перейдите в Settings > Users > Edit your user

3. Убедитесь, что у пользователя есть разрешение Access System API

4. В разделе API Tokens создайте новый токен

5. Скопируйте Token ID и Token Secret

Безопасность

• Операции записи по умолчанию отключены

• Используйте HTTPS для продакшен-инстансов

• Храните API-токены безопасно (никогда не коммитьте в git)

• Рассмотрите возможность создания выделенного пользователя BookStack с ограниченными правами

Разработка

npm run dev          # Hot reload with tsx
npm run type-check   # Type checking only
npm run build        # Production build

Лицензия

MIT