Nextcloud MCP - MCP Servers

Nextcloud MCP Server

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

Use Claude, GPT, Gemini, and other MCP-compatible clients to create notes, manage calendars, work with contacts, and browse files through natural language workflows.

Quick Start (NixOS First)

This repository now includes:

flake.nix for a dev shell and runnable app
nixosModules.default for service deployment on NixOS
tools/nextcloud-mcp-server.service as a generic systemd template

1) Add this repository as an input in your system flake

{
  inputs.nextcloud-mcp-server.url = "github:YOUR_ORG/nextcloud-mcp-server";
}

2) Enable the module in your NixOS configuration

{
  imports = [ inputs.nextcloud-mcp-server.nixosModules.default ];

  services.nextcloud-mcp-server = {
    enable = true;
    workingDirectory = "/srv/nextcloud-mcp-server";
    environmentFile = "/etc/nextcloud-mcp-server.env";
    host = "127.0.0.1";
    port = 8000;
    transport = "streamable-http";
    metricsPort = 9090;
  };
}

3) Create the environment file with Nextcloud credentials

sudo install -m 0600 -o root -g root /dev/null /etc/nextcloud-mcp-server.env
sudo tee /etc/nextcloud-mcp-server.env >/dev/null <<'EOF'
NEXTCLOUD_HOST=https://cloud.example.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password
EOF

4) Deploy and verify

sudo nixos-rebuild switch
systemctl --no-pager --full status nextcloud-mcp-server
curl -fsS http://127.0.0.1:8000/health/ready

5) Connect your MCP client

http://127.0.0.1:8000/mcp for streamable-http
http://127.0.0.1:8000/sse for SSE transport (if configured)

How Credentials Are Passed

The server reads credentials from environment variables:

NEXTCLOUD_HOST
NEXTCLOUD_USERNAME
NEXTCLOUD_PASSWORD

On NixOS, the recommended method is services.nextcloud-mcp-server.environmentFile.

Security guidance:

Use an app password from Nextcloud, not your interactive account password.
Keep env files outside git (for example, /etc/nextcloud-mcp-server.env).
Restrict file permissions to 0600.
Rotate app passwords if they are ever exposed.
Do not hardcode credentials in configuration.nix, scripts, commit history, or screenshots.

Optional environment variables:

TOKEN_ENCRYPTION_KEY (recommended for encrypted token persistence features)
TOKEN_STORAGE_DB (default is /tmp/tokens.db, override for persistent storage)
METRICS_PORT (default 9090)

LLM Agents: NixOS Install Runbook

Use this section when an agentic LLM session is asked to install and configure this MCP server on a NixOS host.

Inputs the agent should request first

Nextcloud URL
Nextcloud username
Nextcloud app password
Desired MCP bind host and port
Whether reverse proxy/TLS is required

Agent workflow checklist

Confirm host is NixOS and flake-based.
Add this repo as a flake input.
Import nixosModules.default.
Configure services.nextcloud-mcp-server.
Create /etc/nextcloud-mcp-server.env with 0600 permissions.
Apply config with nixos-rebuild switch.
Validate service health endpoint.
Run an MCP smoke test (list a directory, read a file).

Command sequence for an agent session

sudo install -d -m 0755 /srv/nextcloud-mcp-server
sudo install -m 0600 -o root -g root /dev/null /etc/nextcloud-mcp-server.env
sudoedit /etc/nextcloud-mcp-server.env
sudo nixos-rebuild switch
systemctl --no-pager --full status nextcloud-mcp-server
curl -fsS http://127.0.0.1:8000/health/ready

Agent completion criteria

A successful agent run should return:

Service state (active (running))
Health check payload from /health/ready
MCP endpoint URL
Any required follow-up (reverse proxy, firewall, OAuth mode, backups)

Alternative Quick Starts

Docker (Self-Hosted)

cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

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

curl http://127.0.0.1:8000/health/ready

Smithery (Managed)

Use Smithery for hosted setup.

[!NOTE] Smithery runs in stateless mode without full semantic-search infrastructure by default.

Key Features

90+ MCP tools across major Nextcloud apps
MCP resources for structured URI-based data access
Semantic search (experimental) with optional vector infrastructure
Document processing (OCR/text extraction for supported files)
Flexible deployment: NixOS, Docker, Kubernetes, VM, local
Authentication modes: Basic Auth (recommended), OAuth/OIDC (experimental)
Multiple transports: streamable-http, HTTP, SSE

Supported Apps

| App | Tools | Capabilities | |-----|-------|--------------| | Notes | 7 | Full CRUD, keyword search, semantic search | | Calendar | 20+ | Events, todos, recurrence, attendees | | Contacts | 8 | CardDAV operations and address books | | Files (WebDAV) | 12 | File/folder operations and document processing | | Deck | 15 | Boards, stacks, cards, labels, assignments | | Cookbook | 13 | Recipe management and URL import | | Tables | 5 | Row operations on Nextcloud Tables | | Sharing | 10+ | Share create/list/manage |

Authentication

Basic Auth with app passwords is recommended for production single-user setups.

[!IMPORTANT] OAuth2/OIDC support is experimental and depends on upstream user_oidc behavior. See docs/oauth-upstream-status.md and docs/authentication.md.

Semantic Search

Semantic search is experimental and opt-in:

Disabled by default (ENABLE_SEMANTIC_SEARCH=false)
Requires additional infrastructure (for example Qdrant plus embedding provider)
Supports semantic retrieval workflows for supported apps

See docs/semantic-search-architecture.md and docs/configuration.md.

Documentation

Getting Started

Installation - Docker, Kubernetes, local, VM
NixOS and systemd - Flake/module usage and service templates
Configuration - Environment variables and advanced options
Authentication - Basic Auth vs OAuth2/OIDC setup
Running the Server - Start, manage, troubleshoot

Features

App Documentation - Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables
Document Processing - OCR/text extraction setup
Semantic Search Architecture - Vector search architecture
Vector Sync UI Guide - Browser UI for semantic sync and test

Advanced Topics

OAuth Architecture - OAuth design and flows
OAuth Quick Start - Fast OAuth bootstrap
OAuth Setup Guide - Full OAuth configuration
Troubleshooting - Common issues and fixes
Comparison with Context Agent - Use-case comparison

Contributing

Report bugs or request features: GitHub Issues
Submit improvements: Pull Requests
Development workflow notes: AGENTS.md

Security

Use app passwords for Basic Auth deployments.
Keep credential files out of git.
Prefer least privilege and scoped credentials.
Report security issues privately to maintainers.

License

AGPL-3.0. See LICENSE.

MCP Servers