Nextcloud MCP Server

Готовый к промышленному использованию MCP-сервер, который подключает ИИ-ассистентов к вашему экземпляру Nextcloud.

Позвольте большим языковым моделям, таким как Claude, GPT и Gemini, взаимодействовать с вашими данными Nextcloud через безопасный API. Создавайте заметки, управляйте календарями, организуйте контакты, работайте с файлами и многое другое — и все это с помощью общения на естественном языке.

Это специализированный автономный MCP-сервер, разработанный для внешних MCP-клиентов, таких как Claude Code и IDE. Он работает независимо от Nextcloud (Docker, VM, Kubernetes или локально) и предоставляет глубокие CRUD-операции для приложений Nextcloud.

[!NOTE] Ищете функции ИИ внутри Nextcloud? Nextcloud также предоставляет Context Agent, который обеспечивает работу приложения Assistant и запускается как ExApp внутри Nextcloud. См. docs/comparison-context-agent.md для подробного сравнения вариантов использования.

Быстрый старт (Docker)

Для получения всех функций, включая семантический поиск, запустите с помощью Docker:

# 1. Create a minimal configuration
cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

# 2. Start the server
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# 3. Test the connection
curl http://127.0.0.1:8000/health/ready

# 4. Connect to the endpoint
http://127.0.0.1:8000/sse

# Or with --transport streamable-http
http://127.0.0.1:8000/mcp

Профили Docker Compose (для разработки/тестирования):

docker compose --profile single-user up -d       # Port 8000
docker compose --profile multi-user-basic up -d   # Port 8003
docker compose --profile oauth up -d              # Port 8001
docker compose --profile login-flow up -d         # Port 8004

Следующие шаги:

• Подключите ваш MCP-клиент (Claude Desktop, IDE, mcp dev и т. д.)

• См. docs/installation.md для других вариантов развертывания (локально, Kubernetes)

Related MCP server: Nextcloud MCP Server

Ключевые особенности

• 90+ инструментов MCP — Полный охват API для 8 приложений Nextcloud

• Ресурсы MCP — Структурированные URI данных для просмотра данных Nextcloud

• Семантический поиск (экспериментально) — Опциональный поиск на основе векторов для заметок, файлов, элементов новостей и карточек Deck (требуется Qdrant + Ollama)

• Обработка документов — OCR и извлечение текста из PDF, DOCX, изображений с уведомлениями о прогрессе

• Гибкое развертывание — Docker, Kubernetes (Helm), VM или локальная установка

• Аутентификация промышленного уровня — Basic Auth с паролями приложений (рекомендуется) или OAuth2/OIDC (экспериментально)

• Множественные транспорты — Поддержка SSE, HTTP и потокового HTTP

Поддерживаемые приложения

Хотите увидеть поддержку другого приложения Nextcloud? Откройте issue или предложите pull request!

Аутентификация

[!IMPORTANT] OAuth2/OIDC является экспериментальной функцией и требует ручного патча для приложения user_oidc:

• Требуемый патч: Поддержка Bearer-токенов (issue #1221)

• Последствия: Без патча большинство специфичных для приложений API завершаются ошибками 401

• Рекомендация: Используйте Basic Auth для промышленного использования, пока апстрим-патчи не будут объединены

См. docs/oauth-upstream-status.md для получения информации о статусе патча и обходных путях.

Рекомендуется: Basic Auth с паролями для конкретных приложений обеспечивает безопасную аутентификацию промышленного уровня. См. docs/authentication.md для получения подробной информации о настройке и конфигурации OAuth.

Режимы аутентификации

Сервер поддерживает четыре режима аутентификации:

Однопользовательский (BasicAuth):

• Один набор учетных данных, общий для всех MCP-клиентов

• Простая настройка: имя пользователя + пароль приложения в переменных окружения

• Все клиенты получают доступ к Nextcloud как один и тот же пользователь

• Лучше всего подходит для: личного использования, разработки, однопользовательских развертываний

Многопользовательский (BasicAuth Pass-Through):

• MCP-клиенты отправляют учетные данные через заголовок Authorization

• Сервер передает их в Nextcloud (по умолчанию без сохранения состояния)

• Опциональный автономный доступ для фоновых операций (ENABLE_MULTI_USER_BASIC_AUTH=true)

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

Многопользовательский (OAuth):

• Каждый MCP-клиент аутентифицируется отдельно со своей учетной записью Nextcloud

• Области доступа и разрешения для каждого пользователя (клиенты видят только те инструменты, на которые они авторизованы)

• Более безопасно: токены истекают, учетные данные никогда не передаются серверу

• Лучше всего подходит для: команд, многопользовательских развертываний, промышленных сред с несколькими пользователями

• Требует: патчей для приложения user_oidc (экспериментально)

Многопользовательский (Login Flow v2):

• Использует встроенный в Nextcloud Login Flow v2 для получения паролей приложений для каждого пользователя

• Патчи OAuth не требуются — работает со стандартным Nextcloud

• Каждый пользователь аутентифицируется через браузер, сервер управляет паролями приложений

• Лучше всего подходит для: многопользовательских развертываний без инфраструктуры OAuth (ENABLE_LOGIN_FLOW=true)

• Экспериментально: см. ADR-022 для подробностей

См. docs/authentication.md для получения подробных инструкций по настройке.

Семантический поиск

Сервер предоставляет экспериментальный RAG-конвейер для включения семантического поиска, который позволяет MCP-клиентам находить информацию в Nextcloud на основе смысла, а не только ключевых слов. Вместо того чтобы находить «машинное обучение» только тогда, когда эти слова встречаются буквально, он понимает, что «нейронные сети», «ИИ-модели» и «глубокое обучение» — это семантически связанные концепции.

Пример:

• Поиск по ключевым словам: Запрос «авто» находит только заметки, содержащие слово «авто»

• Семантический поиск: Запрос «авто» также находит заметки об «автомобиле», «транспортном средстве», «седане», «перевозках»

Это позволяет использовать запросы на естественном языке и помогает находить связанный контент в ваших заметках Nextcloud.

[!NOTE] Семантический поиск является экспериментальным и требует включения:

• По умолчанию отключен (ENABLE_SEMANTIC_SEARCH=false)

• В настоящее время поддерживает только приложение Notes (планируется поддержка нескольких приложений)

• Требует дополнительной инфраструктуры: векторная база данных + сервис эмбеддингов

• Генерация ответов (nc_semantic_search_answer) требует поддержки сэмплирования со стороны MCP-клиента

См. docs/semantic-search-architecture.md для получения подробной информации об архитектуре и docs/configuration.md для инструкций по настройке.

Документация

Начало работы

• Установка — Развертывание в Docker, Kubernetes, локально или на VM

• Конфигурация — Переменные окружения и расширенные опции

• Аутентификация — Настройка Basic Auth против OAuth2/OIDC

• Запуск сервера — Запуск, управление и устранение неполадок

Функции

• Документация по приложениям — Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables

• Обработка документов — Настройка OCR и извлечения текста

• Архитектура семантического поиска — Экспериментальный векторный поиск (Notes, Files, News items, Deck cards; по выбору)

• Руководство по Vector Sync UI — Интерфейс браузера для визуализации и тестирования семантического поиска

Продвинутые темы

• Архитектура OAuth — Как работает OAuth (экспериментально)

• Быстрый старт OAuth — 5-минутная настройка OAuth

• Руководство по настройке OAuth — Подробная конфигурация OAuth

• Устранение неполадок — Распространенные проблемы и решения

• Сравнение с Context Agent — Когда использовать каждый подход

Примеры

Создание заметки

AI: "Create a note called 'Meeting Notes' with today's agenda"
→ Uses nc_notes_create_note tool

Импорт рецептов

AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction

Планирование встреч

AI: "Schedule a team meeting for next Tuesday at 2pm"
→ Uses nc_calendar_create_event tool

Управление файлами

AI: "Create a folder called 'Project X' and move all PDFs there"
→ Uses nc_webdav_create_directory and nc_webdav_move tools

Семантический поиск (экспериментально, по выбору)

AI: "Find notes related to machine learning concepts"
→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)

Примечание: Для ответов, сгенерированных ИИ с цитатами, используйте nc_semantic_search_answer (требуется MCP-клиент с поддержкой сэмплирования).

Вклад в проект

Мы приветствуем любой вклад!

• Сообщайте об ошибках или запрашивайте функции: GitHub Issues

• Предлагайте улучшения: Pull Requests

• Руководство по разработке: CLAUDE.md

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

Этот проект серьезно относится к безопасности:

• Готовая к промышленному использованию Basic Auth с паролями для конкретных приложений

• Поддержка OAuth2/OIDC (экспериментально, требует патчей апстрима)

• Токены доступа для каждого пользователя

• Отсутствие хранения учетных данных в режиме OAuth

• Регулярные оценки безопасности

Нашли проблему безопасности? Пожалуйста, сообщите о ней конфиденциально сопровождающим проекта.

Лицензия

Этот проект лицензирован по лицензии AGPL-3.0. См. LICENSE для получения подробной информации.

История звезд

Ссылки

• Model Context Protocol

• MCP Python SDK

• Nextcloud