Nextcloud MCP Server

Experimental — This repository is fully maintained by AI (Claude). It serves as an experiment in autonomous AI-driven open-source development.

An MCP (Model Context Protocol) server that exposes Nextcloud APIs as tools for AI assistants. Connect any MCP-compatible client (Claude Desktop, Claude Code, etc.) to your Nextcloud instance and let AI manage your files, calendar, contacts, conversations, and more.

Quick Start

pip install nc-mcp-server

Set environment variables and connect:

export NEXTCLOUD_URL=https://your-nextcloud.example.com
export NEXTCLOUD_USER=your-username
export NEXTCLOUD_PASSWORD=your-app-password
nc-mcp-server

140 Tools Across 23 Nextcloud Apps

A 141st tool, upload_file_from_path, is registered only when the operator sets NEXTCLOUD_MCP_UPLOAD_ROOT. See Files for details.

Category	Tools	Protocol
Files	list, read, search, upload (text / binary / from path), copy, move, delete	WebDAV
File Sharing	list, get, create, update, delete shares	OCS
Trashbin	list, restore, delete item, empty trash	WebDAV
File Versions	list, restore versions	WebDAV
File Comments	list, add, edit, delete comments	WebDAV
File Reminders	get, set, remove per-file reminders	OCS
System Tags	list, create, assign, unassign, delete tags	WebDAV
Users	get current, list, get, create, delete users	OCS
User Status	get, set, clear status	OCS
Notifications	list, dismiss one, dismiss all	OCS
Activity	get activity feed with filtering	OCS
Talk	conversations, messages, participants	OCS
Talk Polls	get, create, vote, close polls	OCS
Announcements	list, create, delete announcements	OCS
Calendar	list calendars, CRUD events	CalDAV
Contacts	list address books, CRUD contacts	CardDAV
Tasks	list lists, CRUD tasks, complete	CalDAV
Mail	accounts, mailboxes, messages, send	OCS
Collectives	list, pages, create, trash, restore	OCS
Forms	CRUD forms, questions, options, shares, submissions + export	OCS
Circles (Teams)	list, CRUD, members (add/remove/promote), join/leave, search	OCS
Unified Search	list providers, search across apps	OCS
App Management	list, info, enable, disable apps	OCS

Security: Permission Model

Every tool has a required permission level. You control what the AI is allowed to do:

Level	What it can do	Environment variable
`read` (default)	List files, read files, get users, view notifications	`NEXTCLOUD_MCP_PERMISSIONS=read`
`write`	Everything in `read` + upload files, send messages, create events	`NEXTCLOUD_MCP_PERMISSIONS=write`
`destructive`	Everything in `write` + delete files, remove shares, empty trash	`NEXTCLOUD_MCP_PERMISSIONS=destructive`

If a tool is called without sufficient permission, it returns a clear error explaining what permission is needed — no silent failures, no accidental deletions.

Installation

pip install nc-mcp-server

Or with pipx / uvx for isolated installation:

pipx install nc-mcp-server
# or
uvx nc-mcp-server

Or from source:

git clone https://github.com/cloud-py-api/nc_mcp_server.git
cd nc_mcp_server
pip install -e .

Configuration

Set these environment variables:

# Required
export NEXTCLOUD_URL=https://your-nextcloud.example.com
export NEXTCLOUD_USER=your-username
export NEXTCLOUD_PASSWORD=your-app-password  # Use an app password, not your main password!

# Optional
export NEXTCLOUD_MCP_PERMISSIONS=read  # read (default), write, or destructive
export NEXTCLOUD_MCP_RETRY_MAX=3       # max retries on 429/503 (default: 3, 0 to disable)
export NEXTCLOUD_MCP_UPLOAD_ROOT=      # unset (default). If set to an absolute directory,
                                       # enables upload_file_from_path, restricted to files
                                       # inside that directory (symlinks resolved).

Getting an App Password

Log into your Nextcloud instance
Go to Settings > Security
Under "Devices & sessions", create a new app password
Use this password for NEXTCLOUD_PASSWORD

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nextcloud": {
      "command": "nc-mcp-server",
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.example.com",
        "NEXTCLOUD_USER": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password",
        "NEXTCLOUD_MCP_PERMISSIONS": "read"
      }
    }
  }
}

With Claude Code

claude mcp add nextcloud \
  -e NEXTCLOUD_URL=https://your-nextcloud.example.com \
  -e NEXTCLOUD_USER=your-username \
  -e NEXTCLOUD_PASSWORD=your-app-password \
  -e NEXTCLOUD_MCP_PERMISSIONS=read \
  -- nc-mcp-server

As HTTP Server (for containers/remote)

nc-mcp-server --transport http
# Listens on http://0.0.0.0:8100 by default

Stdio Mode (default)

nc-mcp-server
# Communicates via stdin/stdout — used by MCP clients like Claude Desktop

Available Tools

Files

Tool	Permission	Description
`list_directory`	read	List files and folders in a directory
`get_file`	read	Read a file's content (returns images as MCP ImageContent)
`search_files`	read	Search files by name, MIME type, or path pattern
`upload_file`	write	Upload or overwrite a text file
`upload_file_binary`	write	Upload or overwrite a binary file (images, PDFs, archives) from base64-encoded content
`upload_file_from_path`	write	Stream a local file from the server's filesystem — only registered when `NEXTCLOUD_MCP_UPLOAD_ROOT` is set
`create_directory`	write	Create a new directory
`copy_file`	write	Copy a file or directory
`move_file`	destructive	Move or rename a file
`delete_file`	destructive	Delete a file or directory (moves to trash)

upload_file_from_path is off by default because it gives the AI read access to the local filesystem. To enable it, set NEXTCLOUD_MCP_UPLOAD_ROOT to an absolute directory — only files resolving inside that directory (after symlink resolution) can be uploaded. This is the right choice when you need to upload multi-GB files that would blow past the size limit of an inline base64 tool call; the body is streamed in chunks rather than loaded into memory.

File Sharing

Tool	Permission	Description
`list_shares`	read	List shares for a file/folder or all shares
`get_share`	read	Get details of a specific share
`create_share`	write	Share a file/folder (user, group, public link, email)
`update_share`	write	Update share permissions, expiration, password, etc.
`delete_share`	destructive	Remove a share

Trashbin

Tool	Permission	Description
`list_trash`	read	List deleted files in the trash bin
`restore_trash_item`	write	Restore a file from trash to its original location
`delete_trash_item`	destructive	Permanently delete a single item from trash
`empty_trash`	destructive	Permanently delete all items in trash

File Versions

Tool	Permission	Description
`list_versions`	read	List version history of a file
`restore_version`	write	Restore a previous version of a file

File Comments

Tool	Permission	Description
`list_comments`	read	List comments on a file
`add_comment`	write	Add a comment to a file
`edit_comment`	write	Edit an existing comment
`delete_comment`	destructive	Delete a comment

File Reminders

Tool	Permission	Description
`get_file_reminder`	read	Get the reminder set on a file (null if none)
`set_file_reminder`	write	Set or replace a reminder due date (ISO 8601, must be in the future)
`remove_file_reminder`	destructive	Remove the reminder from a file

System Tags

Tool	Permission	Description
`list_tags`	read	List all available tags
`get_file_tags`	read	Get tags assigned to a file
`create_tag`	write	Create a new tag
`assign_tag`	write	Assign a tag to a file
`unassign_tag`	destructive	Remove a tag from a file
`delete_tag`	destructive	Delete a tag

Users

Tool	Permission	Description
`get_current_user`	read	Get current authenticated user info
`list_users`	read	List or search users
`get_user`	read	Get specific user details
`create_user`	write	Create a new user (admin only)
`delete_user`	destructive	Delete a user (admin only)

User Status

Tool	Permission	Description
`get_user_status`	read	Get a user's status (online, away, dnd, etc.)
`set_user_status`	write	Set your status and custom message
`clear_user_status`	destructive	Clear your status

Notifications

Tool	Permission	Description
`list_notifications`	read	List all notifications
`dismiss_notification`	write	Dismiss a single notification
`dismiss_all_notifications`	write	Dismiss all notifications

Activity

Tool	Permission	Description
`get_activity`	read	View recent activity with filtering, sorting, and pagination

Talk

Tool	Permission	Description
`list_conversations`	read	List all Talk conversations
`get_conversation`	read	Get conversation details
`get_messages`	read	Get messages from a conversation
`get_participants`	read	List participants in a conversation
`send_message`	write	Send a message to a conversation
`create_conversation`	write	Create a new conversation
`delete_message`	destructive	Delete a message
`leave_conversation`	destructive	Leave a conversation

Talk Polls

Tool	Permission	Description
`get_poll`	read	Get poll details and results
`create_poll`	write	Create a poll in a conversation
`vote_poll`	write	Vote on a poll
`close_poll`	write	Close a poll

Announcements

Tool	Permission	Description
`list_announcements`	read	List announcements
`create_announcement`	write	Create an announcement
`delete_announcement`	destructive	Delete an announcement

Calendar

Tool	Permission	Description
`list_calendars`	read	List user's calendars
`get_events`	read	Get events from a calendar (with date filtering)
`get_event`	read	Get a single event by UID
`create_event`	write	Create a calendar event
`update_event`	write	Update an event (partial updates supported)
`delete_event`	destructive	Delete a calendar event

Contacts

Tool	Permission	Description
`list_addressbooks`	read	List user's address books
`get_contacts`	read	Get contacts with pagination
`get_contact`	read	Get a single contact by UID
`create_contact`	write	Create a contact (multi-value email/phone supported)
`update_contact`	write	Update a contact (ETag concurrency control)
`delete_contact`	destructive	Delete a contact

Tasks

Tool	Permission	Description
`list_task_lists`	read	List task lists (CalDAV VTODO collections)
`get_tasks`	read	List tasks in a list (with status/completed filters)
`get_task`	read	Get a single task by UID
`create_task`	write	Create a task (due date, priority, categories, etc.)
`update_task`	write	Update a task (partial updates supported)
`complete_task`	write	Mark a task as completed
`delete_task`	destructive	Delete a task

Mail

Tool	Permission	Description
`list_mail_accounts`	read	List mail accounts
`list_mailboxes`	read	List mailboxes (folders) for an account
`list_mail_messages`	read	List messages in a mailbox
`get_mail_message`	read	Get full message content
`send_mail`	write	Send an email

Collectives

Tool	Permission	Description
`list_collectives`	read	List all collectives
`get_collective_pages`	read	List pages in a collective
`get_collective_page`	read	Get a page's content
`create_collective`	write	Create a new collective
`create_collective_page`	write	Create a page in a collective
`trash_collective`	destructive	Move a collective to trash
`delete_collective`	destructive	Permanently delete a trashed collective
`trash_collective_page`	destructive	Move a page to trash
`delete_collective_page`	destructive	Permanently delete a trashed page
`restore_collective`	write	Restore a collective from trash
`restore_collective_page`	write	Restore a page from trash

Forms

Tool	Permission	Description
`list_forms`	read	List forms (filter by ownership: "owned" or "shared"; omit to merge both)
`get_form`	read	Get a form with questions, options, shares
`list_questions`	read	List questions on a form
`get_question`	read	Get a single question
`list_submissions`	read	List submissions (owner only), with pagination and text filter
`get_submission`	read	Get a single submission with answers
`create_form`	write	Create an empty form or clone from an existing form
`update_form`	write	Update form properties (title, access, state, maxSubmissions, etc.)
`create_question`	write	Add a question (short, long, multiple, dropdown, date, file, grid, …)
`update_question`	write	Update question properties
`reorder_questions`	write	Reorder all questions on a form
`create_options`	write	Add answer options to a choice question
`update_option`	write	Update option text
`reorder_options`	write	Reorder options within a question
`create_form_share`	write	Share a form with user, group, circle, or link
`update_form_share`	write	Update share permissions
`submit_form`	write	Submit answers to a form
`update_submission`	write	Edit an existing submission (requires allowEditSubmissions)
`export_submissions`	write	Export submissions as a spreadsheet to a Nextcloud folder
`delete_form`	destructive	Delete a form and all its content
`delete_question`	destructive	Delete a question
`delete_option`	destructive	Delete an option
`delete_form_share`	destructive	Revoke a share
`delete_submission`	destructive	Delete one submission
`delete_all_submissions`	destructive	Delete every submission on a form

Circles (Teams)

Tool	Permission	Description
`list_circles`	read	List circles the current user can see
`get_circle`	read	Get a single circle including the current user's membership
`list_circle_members`	read	List members of a circle
`search_circles`	read	Search circles and candidate members (users/groups/mail) by term
`create_circle`	write	Create a circle; caller becomes owner
`update_circle_name`	write	Rename a circle
`update_circle_description`	write	Update description
`update_circle_config`	write	Update config bitmask (VISIBLE, OPEN, INVITE, HIDDEN, etc.)
`add_circle_member`	write	Add a user, group, email, or nested circle as a member
`update_circle_member_level`	write	Promote/demote a member (member/moderator/admin/owner)
`join_circle`	write	Join an open circle
`leave_circle`	write	Leave a circle
`delete_circle`	destructive	Delete a circle
`remove_circle_member`	destructive	Kick a member

Unified Search

Tool	Permission	Description
`list_search_providers`	read	List available search providers (files, mail, talk, etc.)
`unified_search`	read	Search across one or more providers with pagination

App Management

Tool	Permission	Description
`list_apps`	read	List installed apps
`get_app_info`	read	Get detailed app information
`enable_app`	write	Enable an app (admin only)
`disable_app`	destructive	Disable an app (admin only)

Development

# Clone and install
git clone https://github.com/cloud-py-api/nc_mcp_server.git
cd nc_mcp_server
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest                              # Unit tests
pytest tests/integration/ -v        # Integration tests (needs running Nextcloud)

# Lint & type check
ruff check . && ruff format --check .
pyright

Integration Tests

Integration tests run against a real Nextcloud instance. Set the environment variables and run:

export NEXTCLOUD_URL=http://localhost:8080
export NEXTCLOUD_USER=admin
export NEXTCLOUD_PASSWORD=admin
pytest tests/integration/ -v

CI automatically runs integration tests against Nextcloud 32 and 33 Docker containers.

About This Project

This project is an experiment in AI-autonomous open-source development. The entire codebase — including this README — is written and maintained by Claude (Anthropic's AI assistant). Human oversight is limited to:

High-level design decisions
Code review of pull requests
Resolving architectural questions

The goal is to explore how far autonomous AI development can go in building production-quality, well-tested software.

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.github		.github
scripts		scripts
src/nc_mcp_server		src/nc_mcp_server
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
GUIDANCE.md		GUIDANCE.md
LICENSE		LICENSE
PROGRESS.md		PROGRESS.md
README.md		README.md
codecov.yml		codecov.yml
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Nextcloud MCP Server

Quick Start

140 Tools Across 23 Nextcloud Apps

Security: Permission Model

Installation

Configuration

Getting an App Password

Usage

With Claude Desktop

With Claude Code

As HTTP Server (for containers/remote)

Stdio Mode (default)

Available Tools

Files

File Sharing

Trashbin

File Versions

File Comments

File Reminders

System Tags

Users

User Status

Notifications

Activity

Talk

Talk Polls

Announcements

Calendar

Contacts

Tasks

Mail

Collectives

Forms

Circles (Teams)

Unified Search

App Management

Development

Integration Tests

About This Project

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages