Servidor MCP de Nextcloud

Un servidor MCP listo para producción que conecta asistentes de IA a tu instancia de Nextcloud.

Permite que modelos de lenguaje grandes como Claude, GPT y Gemini interactúen con tus datos de Nextcloud a través de una API segura. Crea notas, gestiona calendarios, organiza contactos, trabaja con archivos y más, todo mediante conversaciones en lenguaje natural.

Este es un servidor MCP independiente y dedicado diseñado para clientes MCP externos como Claude Code e IDEs. Se ejecuta independientemente de Nextcloud (Docker, VM, Kubernetes o local) y proporciona operaciones CRUD profundas en las aplicaciones de Nextcloud.

[!NOTE] ¿Buscas funciones de IA dentro de Nextcloud? Nextcloud también proporciona Context Agent, que potencia la aplicación Assistant y se ejecuta como una ExApp dentro de Nextcloud. Consulta docs/comparison-context-agent.md para una comparación detallada de los casos de uso.

Inicio rápido (Docker)

Para obtener todas las funciones, incluida la búsqueda semántica, ejecútalo con 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

Perfiles de Docker Compose (para desarrollo/pruebas):

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

Próximos pasos:

• Conecta tu cliente MCP (Claude Desktop, IDEs, mcp dev, etc.)

• Consulta docs/installation.md para otras opciones de despliegue (local, Kubernetes)

Related MCP server: Nextcloud MCP Server

Características clave

• Más de 90 herramientas MCP - Cobertura completa de API en 8 aplicaciones de Nextcloud

• Recursos MCP - URIs de datos estructurados para navegar por los datos de Nextcloud

• Búsqueda semántica (Experimental) - Búsqueda opcional basada en vectores para Notas, Archivos, elementos de Noticias y tarjetas de Deck (requiere Qdrant + Ollama)

• Procesamiento de documentos - OCR y extracción de texto de PDFs, DOCX e imágenes con notificaciones de progreso

• Despliegue flexible - Docker, Kubernetes (Helm), VM o instalación local

• Autenticación lista para producción - Autenticación básica con contraseñas de aplicación (recomendado) o OAuth2/OIDC (experimental)

• Múltiples transportes - Soporte para SSE, HTTP y HTTP con streaming

Aplicaciones compatibles

¿Quieres ver otra aplicación de Nextcloud compatible? Abre un issue o envía un pull request.

Autenticación

[!IMPORTANT] OAuth2/OIDC es experimental y requiere un parche manual en la aplicación user_oidc:

• Parche requerido: Soporte para token Bearer (issue #1221)

• Impacto: Sin el parche, la mayoría de las APIs específicas de la aplicación fallan con errores 401

• Recomendación: Usa autenticación básica para producción hasta que se fusionen los parches upstream

Consulta docs/oauth-upstream-status.md para conocer el estado del parche y las soluciones alternativas.

Recomendado: La autenticación básica con contraseñas específicas de la aplicación proporciona una autenticación segura y lista para producción. Consulta docs/authentication.md para obtener detalles de configuración y configuración de OAuth.

Modos de autenticación

El servidor admite cuatro modos de autenticación:

Usuario único (BasicAuth):

• Un conjunto de credenciales compartido por todos los clientes MCP

• Configuración sencilla: nombre de usuario + contraseña de aplicación en variables de entorno

• Todos los clientes acceden a Nextcloud como el mismo usuario

• Ideal para: Uso personal, desarrollo, despliegues de usuario único

Multiusuario (Paso a través de BasicAuth):

• Los clientes MCP envían credenciales a través del encabezado Authorization

• El servidor las pasa a Nextcloud (sin estado por defecto)

• Acceso offline opcional para operaciones en segundo plano (ENABLE_MULTI_USER_BASIC_AUTH=true)

• Ideal para: Configuraciones multiusuario sin infraestructura OAuth

Multiusuario (OAuth):

• Cada cliente MCP se autentica por separado con su propia cuenta de Nextcloud

• Alcances y permisos por usuario (los clientes solo ven las herramientas para las que están autorizados)

• Más seguro: los tokens caducan, las credenciales nunca se comparten con el servidor

• Ideal para: Equipos, despliegues multiusuario, entornos de producción con múltiples usuarios

• Requiere: Parches en la aplicación user_oidc (experimental)

Multiusuario (Login Flow v2):

• Utiliza el flujo de inicio de sesión nativo v2 de Nextcloud para obtener contraseñas de aplicación por usuario

• No se requieren parches de OAuth: funciona con Nextcloud estándar

• Cada usuario se autentica a través del navegador, el servidor gestiona las contraseñas de aplicación

• Ideal para: Despliegues multiusuario sin infraestructura OAuth (ENABLE_LOGIN_FLOW=true)

• Experimental: Consulta ADR-022 para más detalles

Consulta docs/authentication.md para obtener instrucciones de configuración detalladas.

Búsqueda semántica

El servidor proporciona una canalización RAG experimental para habilitar la Búsqueda semántica, que permite a los clientes MCP encontrar información en Nextcloud basada en el significado en lugar de solo palabras clave. En lugar de coincidir con "aprendizaje automático" solo cuando aparecen esas palabras exactas, entiende que "redes neuronales", "modelos de IA" y "aprendizaje profundo" son conceptos semánticamente relacionados.

Ejemplo:

• Búsqueda por palabras clave: La consulta "coche" solo encuentra notas que contienen "coche"

• Búsqueda semántica: La consulta "coche" también encuentra notas sobre "automóvil", "vehículo", "sedán", "transporte"

Esto permite consultas en lenguaje natural y ayuda a descubrir contenido relacionado en tus notas de Nextcloud.

[!NOTE] La búsqueda semántica es experimental y opcional:

• Deshabilitada por defecto (ENABLE_SEMANTIC_SEARCH=false)

• Actualmente solo admite la aplicación Notas (se planea soporte para múltiples aplicaciones)

• Requiere infraestructura adicional: base de datos vectorial + servicio de incrustación (embedding)

• La generación de respuestas (nc_semantic_search_answer) requiere soporte de muestreo del cliente MCP

Consulta docs/semantic-search-architecture.md para detalles de arquitectura y docs/configuration.md para instrucciones de configuración.

Documentación

Primeros pasos

• Instalación - Despliegue en Docker, Kubernetes, local o VM

• Configuración - Variables de entorno y opciones avanzadas

• Autenticación - Configuración de Basic Auth vs OAuth2/OIDC

• Ejecución del servidor - Iniciar, gestionar y solucionar problemas

Características

• Documentación de la aplicación - Notas, Calendario, Contactos, WebDAV, Deck, Cookbook, Tablas

• Procesamiento de documentos - Configuración de OCR y extracción de texto

• Arquitectura de búsqueda semántica - Búsqueda vectorial experimental (Notas, Archivos, elementos de Noticias, tarjetas de Deck; opcional)

• Guía de la interfaz de usuario de sincronización vectorial - Interfaz de navegador para visualización y prueba de búsqueda semántica

Temas avanzados

• Arquitectura OAuth - Cómo funciona OAuth (experimental)

• Inicio rápido de OAuth - Configuración de OAuth en 5 minutos

• Guía de configuración de OAuth - Configuración detallada de OAuth

• Solución de problemas - Problemas comunes y soluciones

• Comparación con Context Agent - Cuándo usar cada enfoque

Ejemplos

Crear una nota

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

Importar recetas

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

Programar reuniones

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

Gestionar archivos

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

Búsqueda semántica (Experimental, opcional)

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

Nota: Para respuestas generadas por IA con citas, usa nc_semantic_search_answer (requiere cliente MCP con soporte de muestreo).

Contribución

¡Las contribuciones son bienvenidas!

• Informar errores o solicitar funciones: GitHub Issues

• Enviar mejoras: Pull Requests

• Guías de desarrollo: CLAUDE.md

Seguridad

Este proyecto se toma la seguridad en serio:

• Autenticación básica lista para producción con contraseñas específicas de la aplicación

• Soporte para OAuth2/OIDC (experimental, requiere parches upstream)

• Tokens de acceso por usuario

• Sin almacenamiento de credenciales en modo OAuth

• Evaluaciones de seguridad periódicas

¿Encontraste un problema de seguridad? Por favor, infórmalo de forma privada a los mantenedores.

Licencia

Este proyecto está bajo la licencia AGPL-3.0. Consulta LICENSE para más detalles.

Historial de estrellas

Referencias

• Model Context Protocol

• SDK de Python para MCP

• Nextcloud