Nextcloud MCP Server

How to use

You connect an MCP client to the Nextcloud MCP server endpoint to perform tasks across your Nextcloud apps. Use the hosted endpoint for quick access or run a self-hosted instance on your own VPS for full control. The server exposes a set of tools that your MCP client can invoke to manage notes, calendar events, contacts, tables, and WebDAV files.

How to install

Prerequisites: Node.js 18+ and access to a Nextcloud instance. You will typically use npm or Docker to run the MCP server.

# Install globally (recommended for quick access)
npm install -g mcp-nextcloud

# Or install locally in your project
npm install mcp-nextcloud

Run the MCP server directly after installation. If installed globally, you can start it with the following command. If installed locally, you can run it via npx or npm scripts.

# If installed globally
mcp-nextcloud

# If installed locally
npx mcp-nextcloud

# Or via npm script
npm exec mcp-nextcloud

Environment setup: Create a .env file with your Nextcloud credentials. Use an App Password rather than your main login password for security.

NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

If you prefer to run a self-hosted VPS instance, you can deploy using Docker or run the server directly after building.

# Docker-based VPS deployment (recommended for VPS)
docker compose up -d --build

# Or build and start directly (local development)
npm run build
npm run start:http

Client configuration example (in your MCP client) points to the hosted endpoint or your self-hosted URL. You will configure the server with your Nextcloud host and credentials in your MCP client settings.

Configuration and security

Security: Use a dedicated Nextcloud App Password for authentication. Do not reuse your main login password. Keep credentials in a secure environment and avoid embedding them in client configurations. You can supply credentials via environment variables (for local deployments) or via secure configuration interfaces when deploying withSmithery.

Environment variables you may use in a local setup include NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD. If you run through the hosted endpoint, credentials can be provided via the MCP client configuration or through the URL query parameters in the endpoint URL.

Troubleshooting

Common issues and fixes include verifying that your Nextcloud apps (Notes, Calendar, Contacts, Tables) are installed and enabled, ensuring the app password has the necessary permissions, and confirming the Nextcloud host URL is correct and reachable.

If you encounter timeouts or performance issues, consider using a local deployment with a smaller scope first, then scale up. For root directory searches within WebDAV, enable quick search and limit the scope of your queries to improve responsiveness.

Notes on deployment options

The solution supports both hosted usage via a dedicated MCP URL and self-hosted VPS deployment. You can test locally with Smithery for cloud testing and deploy to Smithery cloud if you need cloud-hosted execution. The hosted endpoint is Share-ready and requires no installation on your part for quick experimentation, while the VPS path gives you full control over the runtime and environment.

Summary of steps at a glance

• Install globally with npm install -g mcp-nextcloud
• Or install locally with npm install mcp-nextcloud
• Configure credentials in a .env file with NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD
• Run the server with mcp-nextcloud (global) or npx mcp-nextcloud (local)
• For VPS deployment, run docker compose up -d --build or build and start locally with npm run build and npm run start:http

Tools overview

The server exposes a comprehensive set of tools across five core areas to automate Nextcloud interactions. You can leverage these tools from your MCP client to create, read, update, delete, and search within Notes, manage Calendar events, work with Contacts, manipulate Tables, and perform advanced WebDAV file operations.

nextcloud_notes_create_note

Create a new note with a title, content, and category

nextcloud_notes_update_note

Update an existing note by ID with optional title, content, or category

nextcloud_notes_append_content

Append content to an existing note with a clear separator

nextcloud_notes_search_notes

Search notes by title or content with result filtering

nextcloud_notes_delete_note

Delete a note by ID

nextcloud_calendar_list_calendars

List all calendars available to the user

nextcloud_calendar_create_event

Create a calendar event with summary, description, dates, and location

nextcloud_calendar_list_events

List events from a calendar with optional date filtering

nextcloud_calendar_get_event

Get detailed information about a specific event

nextcloud_calendar_update_event

Update any aspect of an existing event

nextcloud_calendar_delete_event

Delete a calendar event

nextcloud_contacts_list_addressbooks

List all available addressbooks for the user

nextcloud_contacts_create_addressbook

Create a new addressbook with display name and description

nextcloud_contacts_delete_addressbook

Delete an addressbook by ID

nextcloud_contacts_list_contacts

List all contacts in a specific addressbook

nextcloud_contacts_create_contact

Create a new contact with full name, emails, phones, addresses, and organizations

nextcloud_contacts_delete_contact

Delete a contact from an addressbook

nextcloud_tables_list_tables

List all tables available to the user

nextcloud_tables_get_schema

Get the schema/structure of a specific table including columns

nextcloud_tables_read_table

Read all rows from a table

nextcloud_tables_insert_row

Insert a new row into a table with key-value data

nextcloud_tables_update_row

Update an existing row in a table

nextcloud_tables_delete_row

Delete a row from a table

nextcloud_webdav_search_files

Unified search across filenames, content, and metadata for WebDAV files

nextcloud_webdav_list_directory

List files and directories in a Nextcloud path

nextcloud_webdav_read_file

Read file content from Nextcloud

nextcloud_webdav_write_file

Create or update files in Nextcloud with content

nextcloud_webdav_create_directory

Create new directories in Nextcloud

nextcloud_webdav_delete_resource

Delete files or directories from Nextcloud

hello

Verify server connectivity and list all available tools