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
Cospend	shared expense tracking — projects, members, bills	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

1. Log into your Nextcloud instance
2. Go to Settings > Security
3. Under "Devices & sessions", create a new app password
4. 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

Cospend

Shared expense tracking ("who paid for what"). Requires the Cospend app to be installed and enabled. All routes are OCS at /ocs/v2.php/apps/cospend/api/v1/.

Tool	Permission	Description
list_cospend_projects	read	List projects the user can access
get_cospend_project	read	Get full project info (members, balance, shares, settings)
get_cospend_project_statistics	read	Per-member spending stats (paid/spent/balance) with filters
get_cospend_project_settlement	read	Suggested reimbursement transactions to settle a project
list_cospend_members	read	List members of a project
list_cospend_bills	read	List bills with filters (payer, category, search, pagination)
get_cospend_bill	read	Get a single bill
create_cospend_project	write	Create a project (caller becomes ADMIN)
update_cospend_project	write	Update project name, currency, sort, archive, etc.
create_cospend_member	write	Add a member (free-form name or linked to a Nextcloud user)
update_cospend_member	write	Update name/weight/color/activated/userid
create_cospend_bill	write	Create a bill (defaults date to today if neither date nor timestamp set)
update_cospend_bill	write	Update any bill field
delete_cospend_project	destructive	Delete a project and all its data
delete_cospend_member	destructive	Delete (or soft-disable if member has bills)
delete_cospend_bill	destructive	Delete a bill (default: trash; pass move_to_trash=False to purge)

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 the two newest released Nextcloud versions — currently 32 and 33 — using the official Docker images. Nextcloud 34 (GA 2026-06-09) joins the matrix once its image is published on Docker Hub.

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.