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.

Quick Start

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"
      }
    }
  }
}

Docker

For full features including semantic search, run with Docker:

docker run -p 127.0.0.1:8000:8000 --rm \
  -e NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
  -e NEXTCLOUD_USERNAME=your_username \
  -e NEXTCLOUD_PASSWORD=your_app_password \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

Then connect your MCP client (Claude Desktop, IDEs, mcp dev, etc.) to http://127.0.0.1:8000/mcp.

For Kubernetes, see cbcoutinho/helm-charts. For other deployment options and Compose profiles, see docs/installation.md.

Related MCP server: Nextcloud MCP Server

Key Features

• 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, Deck cards, and Mail messages (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; multi-user via Login Flow v2 — MCP clients authenticate via OAuth, the server handles Nextcloud app passwords transparently

• Tag-Based File Exclusion - Hide sensitive files/folders from MCP file tools by tagging them with a configured Nextcloud system tag (EXCLUDED_TAGS). See docs/configuration.md

• Multiple Transports - streamable-http (default) and stdio

Supported Apps

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

Authentication

The MCP server authenticates to Nextcloud using app-specific passwords (Basic Auth). Three deployment modes are supported:

OAuth-direct-to-Nextcloud is no longer supported (it required upstream patches to user_oidc that were never merged). Login Flow v2 replaces it for multi-user deployments and works with stock Nextcloud.

See docs/authentication.md for setup instructions.

AI inside Nextcloud

This server was built for AI assistants that live outside Nextcloud — Claude Code, an IDE, a desktop client. But Nextcloud has its own chat, the Assistant app, and there are two ways to give it access to your content.

Astrolabe is a Nextcloud app that registers itself as the Assistant's agent provider, so no AppAPI and no extra container are involved — the Assistant talks to it, and it searches your content through this server. Each user's questions run under their own identity, so nobody sees anything they couldn't already open.

You can install both and pick per instance, or neither: none of this is required to use this server from an external MCP client.

To set it up, see the Astrolabe setup guide. For the architectural detail behind the comparison, see docs/comparison-context-agent.md.

Semantic Search

An experimental RAG pipeline that lets MCP clients find Nextcloud content by meaning rather than keywords — a query for "car" also surfaces notes about "vehicle" or "transportation". Disabled by default (ENABLE_SEMANTIC_SEARCH=false); requires a vector database and embedding service. See docs/semantic-search-architecture.md and docs/configuration.md.

Documentation

• Installation — Docker, Compose profiles, local, VM

• Configuration — Environment variables, document processing, semantic search setup

• Authentication — Basic Auth, Login Flow v2

• Running the Server — Start, manage, troubleshoot

• App Documentation — Per-app guides (Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables)

• Semantic Search Architecture + Vector Sync UI

• Login Flow v2 — recommended multi-user setup (architecture, env vars, scope reference, troubleshooting)

• Troubleshooting · Comparison with Context Agent

Contributing

Contributions are welcome!

• Report bugs or request features: GitHub Issues

• Submit improvements: Pull Requests

• Development guidelines: CLAUDE.md

Security

Found a security issue? Do not open a public GitHub issue. Use GitHub's private vulnerability reporting, or email security@astrolabecloud.com if you can't use GitHub. See SECURITY.md for details.

License

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

Star History

References

• Model Context Protocol

• MCP Python SDK

• Nextcloud