Nextcloud MCP Server

How to use

To use the Nextcloud MCP Server, start the server locally or in your preferred hosting environment, then connect your MCP client (such as Claude Desktop, IDE integrations, or any MCP client) to the server endpoint. You will interact with Nextcloud data through natural language conversations, covering notes, calendars, contacts, files, decks, recipes, and more. The server supports multiple transport methods and can leverage semantic search in supported configurations.

How to install

Prerequisites: you need Docker installed on your machine for the Docker-based self-hosted setup. You will also create a Nextcloud user and app password to grant access from the MCP server.

Step 1: Create a minimal environment file with Nextcloud credentials.

# 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

Step 2: Start the MCP server using Docker. This runs the server and exposes port 8000 locally.

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

Step 3: Verify the server is ready to accept connections.

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

Step 4: Connect your MCP client to the server endpoint.

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

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

Additional setup options

If you prefer development or testing profiles, you can use Docker Compose profiles to tailor the exposed ports for single-user, multi-user basic, OAuth, or login flow deployments.

Example development profiles (these commands launch containers with different ports):

# Single user
docker compose --profile single-user up -d

# Multi-user basic
docker compose --profile multi-user-basic up -d

# OAuth
docker compose --profile oauth up -d

# Login flow
docker compose --profile login-flow up -d

Notes on deployment options

The server supports Docker, Kubernetes (Helm), VM, and local installations. Choose the deployment method that best fits your environment, scaling needs, and security requirements.

Security and authentication

You can securely authenticate MCP clients using Basic Auth with app passwords or OAuth2/OIDC (experimental). Basic Auth with app-specific passwords is recommended for production until OAuth patches are stabilized.

Semantic features and examples

The server offers an experimental Semantic Search feature that can be enabled to perform vector-based searches across Notes, Files, News items, and Deck cards. This requires additional infrastructure such as a vector database and embedding service.

Examples of common interactions

Create a note, import a recipe, schedule meetings, manage files, and perform semantic searches using natural language prompts. Tools referenced in examples include operations like creating notes, importing recipes, creating calendar events, and managing WebDAV folders.

Troubleshooting and tips

If you encounter authentication errors, verify your credentials and ensure the correct authentication mode is enabled. For semantic search, confirm you have the required vector infrastructure running and that the feature is enabled in configuration.

Disclaimer on features

Some features are experimental or opt-in and may require additional infrastructure or patches. Review the specific guidance for each feature to understand prerequisites and limitations.

Examples of tools and endpoints

You can perform actions via specific tools. Here are representative tool endpoints used in demonstrations:

nc_notes_create_note

Create a new note in the Notes app with specified content and metadata.

nc_cookbook_import_recipe

Import a recipe into the Cookbook app using schema.org metadata extraction.

nc_calendar_create_event

Create a calendar event with title, time, attendees, and recurrence options.

nc_webdav_create_directory

Create a directory in the WebDAV filesystem for organized file storage.

nc_webdav_move

Move files within the WebDAV filesystem to new directories.

nc_semantic_search

Perform a vector-based semantic search across notes, files, and deck items.

nc_semantic_search_answer

Provide cited, generated answers for semantic search results (requires MCP client sampling support).