55[ ![ Integration Tests] ( https://github.com/cloud-py-api/nc-mcp-server/actions/workflows/tests-integration.yml/badge.svg )] ( https://github.com/cloud-py-api/nc-mcp-server/actions/workflows/tests-integration.yml )
66[ ![ codecov] ( https://codecov.io/gh/cloud-py-api/nc-mcp-server/graph/badge.svg )] ( https://codecov.io/gh/cloud-py-api/nc-mcp-server )
77
8+ ![ NextcloudVersion] ( https://img.shields.io/badge/Nextcloud-32%20%7C%2033-blue )
89![ PythonVersion] ( https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue )
9- [ ![ PyPI] ( https://img.shields.io/pypi/v/nc-mcp-server.svg )] ( https://pypi.org/project/nc-mcp-server/ )
1010[ ![ Python] ( https://img.shields.io/pypi/implementation/nc-mcp-server )] ( https://pypi.org/project/nc-mcp-server/ )
11+ [ ![ PyPI] ( https://img.shields.io/pypi/v/nc-mcp-server.svg )] ( https://pypi.org/project/nc-mcp-server/ )
12+ [ ![ License: MIT] ( https://img.shields.io/github/license/cloud-py-api/nc-mcp-server )] ( https://github.com/cloud-py-api/nc-mcp-server/blob/main/LICENSE )
1113
1214> ** Experimental** — This repository is fully maintained by AI (Claude). It serves as an experiment in autonomous AI-driven open-source development.
1315
1416An [ MCP (Model Context Protocol)] ( https://modelcontextprotocol.io/ ) 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 files, read notifications, interact with Talk, and more.
1517
1618## Features
1719
18- - ** File Management** — List, read, upload, move, and delete files via WebDAV
20+ - ** File Management** — List, read, search, upload, move, and delete files via WebDAV
1921- ** User Info** — Get current user, list users, view user details
20- - ** Notifications** — List and dismiss notifications (coming soon)
21- - ** Activity Feed** — View recent activity (coming soon)
22- - ** Talk** — List conversations, read and send messages (coming soon)
22+ - ** Notifications** — List and dismiss notifications
23+ - ** Activity Feed** — View recent activity with filtering and pagination
24+ - ** Talk** — List conversations, read and send messages, manage polls
25+ - ** Comments** — List, add, edit, and delete file comments
2326- ** Security-First** — Granular permission levels control what AI can do
2427
2528## Security: Permission Model
@@ -40,6 +43,13 @@ If a tool is called without sufficient permission, it returns a clear error expl
4043pip install nc-mcp-server
4144```
4245
46+ Or with ` pipx ` / ` uvx ` for isolated installation:
47+ ``` bash
48+ pipx install nc-mcp-server
49+ # or
50+ uvx nc-mcp-server
51+ ```
52+
4353Or from source:
4454``` bash
4555git clone https://github.com/cloud-py-api/nc-mcp-server.git
@@ -90,6 +100,17 @@ Add to your `claude_desktop_config.json`:
90100}
91101```
92102
103+ ### With Claude Code
104+
105+ ``` bash
106+ claude mcp add nextcloud \
107+ -e NEXTCLOUD_URL=https://your-nextcloud.example.com \
108+ -e NEXTCLOUD_USER=your-username \
109+ -e NEXTCLOUD_PASSWORD=your-app-password \
110+ -e NEXTCLOUD_MCP_PERMISSIONS=read \
111+ -- nextcloud-mcp
112+ ```
113+
93114### As HTTP Server (for containers/remote)
94115
95116``` bash
@@ -106,34 +127,80 @@ nextcloud-mcp
106127
107128## Available Tools
108129
109- ### Files (Phase 1 — available now)
130+ ### Files
110131
111132| Tool | Permission | Description |
112133| ------| -----------| -------------|
113134| ` list_directory(path) ` | read | List files and folders |
114135| ` get_file(path) ` | read | Read a file's content |
136+ | ` search_files(name, mime_type, ...) ` | read | Search files by name, type, or path |
115137| ` upload_file(path, content) ` | write | Upload or overwrite a file |
116138| ` create_directory(path) ` | write | Create a new directory |
117139| ` delete_file(path) ` | destructive | Delete a file or directory |
118140| ` move_file(source, destination) ` | destructive | Move or rename a file |
119141
120- ### Users (Phase 1 — available now)
142+ ### Users
121143
122144| Tool | Permission | Description |
123145| ------| -----------| -------------|
124146| ` get_current_user() ` | read | Get current user info |
125147| ` list_users(search, limit) ` | read | List/search users |
126148| ` get_user(user_id) ` | read | Get specific user details |
127149
150+ ### Notifications
151+
152+ | Tool | Permission | Description |
153+ | ------| -----------| -------------|
154+ | ` list_notifications() ` | read | List all notifications |
155+ | ` dismiss_notification(id) ` | write | Dismiss a single notification |
156+ | ` dismiss_all_notifications() ` | write | Dismiss all notifications |
157+
158+ ### Activity
159+
160+ | Tool | Permission | Description |
161+ | ------| -----------| -------------|
162+ | ` get_activity(filter, sort, limit, since) ` | read | View recent activity with filtering and pagination |
163+
164+ ### Talk
165+
166+ | Tool | Permission | Description |
167+ | ------| -----------| -------------|
168+ | ` list_conversations() ` | read | List all Talk conversations |
169+ | ` get_conversation(token) ` | read | Get conversation details |
170+ | ` get_messages(token, ...) ` | read | Get messages from a conversation |
171+ | ` get_participants(token) ` | read | List participants in a conversation |
172+ | ` send_message(token, message) ` | write | Send a message to a conversation |
173+ | ` create_conversation(name, ...) ` | write | Create a new conversation |
174+ | ` delete_message(token, id) ` | destructive | Delete a message |
175+ | ` leave_conversation(token) ` | destructive | Leave a conversation |
176+
177+ ### Talk Polls
178+
179+ | Tool | Permission | Description |
180+ | ------| -----------| -------------|
181+ | ` get_poll(token, poll_id) ` | read | Get poll details and results |
182+ | ` create_poll(token, question, options) ` | write | Create a poll in a conversation |
183+ | ` vote_poll(token, poll_id, options) ` | write | Vote on a poll |
184+ | ` close_poll(token, poll_id) ` | write | Close a poll |
185+
186+ ### Comments
187+
188+ | Tool | Permission | Description |
189+ | ------| -----------| -------------|
190+ | ` list_comments(path, ...) ` | read | List comments on a file |
191+ | ` add_comment(path, message) ` | write | Add a comment to a file |
192+ | ` edit_comment(path, comment_id, message) ` | write | Edit a comment |
193+ | ` delete_comment(path, comment_id) ` | destructive | Delete a comment |
194+
128195### Coming Soon
129196
130- - ** Notifications** — list and dismiss
131- - ** Activity** — recent activity feed
132- - ** Talk** — conversations and messages
133197- ** Shares** — manage file shares
198+ - ** Trashbin** — view and restore deleted files
199+ - ** File Versions** — list and restore file versions
134200- ** Calendar** — events via CalDAV
135201- ** Contacts** — contacts via CardDAV
136202- ** Deck** — boards and cards
203+ - ** Notes** — manage notes
137204
138205## Development
139206
@@ -164,7 +231,7 @@ export NEXTCLOUD_PASSWORD=admin
164231pytest tests/integration/ -v -m integration
165232```
166233
167- CI automatically runs integration tests against a fresh Nextcloud Docker container .
234+ CI automatically runs integration tests against Nextcloud 32 and 33 Docker containers .
168235
169236## About This Project
170237
0 commit comments