Nextcloud MCP Server

A production-ready MCP server that connects AI assistants to your Nextcloud instance.

Enable Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language conversations.

This is a dedicated standalone MCP server designed for external MCP clients like Claude Code and IDEs. It runs independently of Nextcloud (Docker, VM, Kubernetes, or local) and provides deep CRUD operations across Nextcloud apps.

Run the server locally with uvx (no installation required):

NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
NEXTCLOUD_USERNAME=your_username \
NEXTCLOUD_PASSWORD=your_app_password \
  uvx nextcloud-mcp-server run --transport stdio

Or add it directly to your MCP client configuration (e.g. claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "nextcloud": {
      "command": "uvx",
      "args": ["nextcloud-mcp-server", "run", "--transport", "stdio"],
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

For full features including semantic search, run with 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/mcp

Docker Compose Profiles (for development/testing):

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

Next Steps:

• Connect your MCP client (Claude Desktop, IDEs, mcp dev, etc.)
• See docs/installation.md for other deployment options. For Kubernetes (Helm), see cbcoutinho/helm-charts

• 110+ MCP Tools - Comprehensive API coverage across 10 Nextcloud apps
• MCP Resources - Structured data URIs for browsing Nextcloud data
• Semantic Search (Experimental) - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama)
• Document Processing - OCR and text extraction from PDFs, DOCX, images with progress notifications
• Flexible Deployment - Docker, Kubernetes (Helm chart), VM, or local installation
• Production-Ready Auth - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
• Multiple Transports - streamable-http (default) and stdio

Want to see another Nextcloud app supported? Open an issue or contribute a pull request!

Recommended: Basic Auth with app-specific passwords provides secure, production-ready authentication. See docs/authentication.md for setup details and OAuth configuration.

The server supports four authentication modes:

Single-User (BasicAuth):

• One set of credentials shared by all MCP clients
• Simple setup: username + app password in environment variables
• All clients access Nextcloud as the same user
• Best for: Personal use, development, single-user deployments

Multi-User (BasicAuth Pass-Through):

• MCP clients send credentials via Authorization header
• Server passes through to Nextcloud (stateless by default)
• Optional offline access for background operations (ENABLE_MULTI_USER_BASIC_AUTH=true)
• Best for: Multi-user setups without OAuth infrastructure

Multi-User (OAuth):

• Each MCP client authenticates separately with their own Nextcloud account
• Per-user scopes and permissions (clients only see tools they're authorized for)
• More secure: tokens expire, credentials never shared with server
• Best for: Teams, multi-user deployments, production environments with multiple users
• Requires: Patches to the user_oidc app (experimental)

Multi-User (Login Flow v2):

• Uses Nextcloud's native Login Flow v2 to obtain per-user app passwords
• No OAuth patches required — works with stock Nextcloud
• Each user authenticates via browser, server manages app passwords
• Best for: Multi-user deployments without OAuth infrastructure (ENABLE_LOGIN_FLOW=true)
• Experimental: See ADR-022 for details

See docs/authentication.md for detailed setup instructions.

The server provides an experimental RAG pipeline to enable Semantic Search that enables MCP clients to find information in Nextcloud based on meaning rather than just keywords. Instead of matching "machine learning" only when those exact words appear, it understands that "neural networks," "AI models," and "deep learning" are semantically related concepts.

Example:

• Keyword search: Query "car" only finds notes containing "car"
• Semantic search: Query "car" also finds notes about "automobile," "vehicle," "sedan," "transportation"

This enables natural language queries and helps discover related content across your Nextcloud notes.

• Installation - Docker, local, or VM deployment. Helm chart for Kubernetes
• Configuration - Environment variables and advanced options
• Authentication - Basic Auth vs OAuth2/OIDC setup
• Running the Server - Start, manage, and troubleshoot

• App Documentation - Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables
• Document Processing - OCR and text extraction setup
• Semantic Search Architecture - Experimental vector search (Notes, Files, News items, Deck cards; opt-in)
• Vector Sync UI Guide - Browser interface for semantic search visualization and testing

• OAuth Architecture - How OAuth works (experimental)
• OAuth Quick Start - 5-minute OAuth setup
• OAuth Setup Guide - Detailed OAuth configuration
• Troubleshooting - Common issues and solutions
• Comparison with Context Agent - When to use each approach

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)

Note: For AI-generated answers with citations, use nc_semantic_search_answer (requires MCP client with sampling support).

Contributions are welcome!

• Report bugs or request features: GitHub Issues
• Submit improvements: Pull Requests
• Development guidelines: CLAUDE.md

This project takes security seriously:

• Production-ready Basic Auth with app-specific passwords
• OAuth2/OIDC support (experimental, requires upstream patches)
• Per-user access tokens
• No credential storage in OAuth mode
• Regular security assessments

Found a security issue? Please report it privately to the maintainers.

This project is licensed under the AGPL-3.0 License. See LICENSE for details.

• Model Context Protocol
• MCP Python SDK
• Nextcloud