{"id":47763596,"url":"https://github.com/cloud-py-api/nc_mcp_server","last_synced_at":"2026-04-07T16:01:59.414Z","repository":{"id":345903228,"uuid":"1187350147","full_name":"cloud-py-api/nc_mcp_server","owner":"cloud-py-api","description":"Repository is completely managed by Claude Code without human intervention","archived":false,"fork":false,"pushed_at":"2026-04-01T08:46:00.000Z","size":217,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T12:44:25.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-py-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T16:15:39.000Z","updated_at":"2026-03-31T13:59:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cloud-py-api/nc_mcp_server","commit_stats":null,"previous_names":["cloud-py-api/nextcloud-mcp-server","cloud-py-api/nc-mcp-server","cloud-py-api/nc_mcp_server"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/cloud-py-api/nc_mcp_server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-py-api%2Fnc_mcp_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-py-api%2Fnc_mcp_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-py-api%2Fnc_mcp_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-py-api%2Fnc_mcp_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-py-api","download_url":"https://codeload.github.com/cloud-py-api/nc_mcp_server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-py-api%2Fnc_mcp_server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31518643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T05:56:29.469Z","updated_at":"2026-04-07T16:01:59.387Z","avatar_url":"https://github.com/cloud-py-api.png","language":"Python","readme":"# Nextcloud MCP Server\n\n[![Lint](https://github.com/cloud-py-api/nc_mcp_server/actions/workflows/lint.yml/badge.svg)](https://github.com/cloud-py-api/nc_mcp_server/actions/workflows/lint.yml)\n[![Unit Tests](https://github.com/cloud-py-api/nc_mcp_server/actions/workflows/tests-unit.yml/badge.svg)](https://github.com/cloud-py-api/nc_mcp_server/actions/workflows/tests-unit.yml)\n[![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)\n[![codecov](https://codecov.io/gh/cloud-py-api/nc_mcp_server/graph/badge.svg)](https://codecov.io/gh/cloud-py-api/nc_mcp_server)\n\n![NextcloudVersion](https://img.shields.io/badge/Nextcloud-32%20%7C%2033-blue)\n![PythonVersion](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)\n[![Python](https://img.shields.io/pypi/implementation/nc-mcp-server)](https://pypi.org/project/nc-mcp-server/)\n[![PyPI](https://img.shields.io/pypi/v/nc-mcp-server.svg)](https://pypi.org/project/nc-mcp-server/)\n[![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)\n\n\u003e **Experimental** — This repository is fully maintained by AI (Claude). It serves as an experiment in autonomous AI-driven open-source development.\n\nAn [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.\n\n## Features\n\n- **File Management** — List, read, search, upload, move, and delete files via WebDAV\n- **User Info** — Get current user, list users, view user details\n- **Notifications** — List and dismiss notifications\n- **Activity Feed** — View recent activity with filtering and pagination\n- **Talk** — List conversations, read and send messages, manage polls\n- **Comments** — List, add, edit, and delete file comments\n- **Security-First** — Granular permission levels control what AI can do\n\n## Security: Permission Model\n\nEvery tool has a required permission level. You control what the AI is allowed to do:\n\n| Level | What it can do | Environment variable |\n|-------|---------------|---------------------|\n| `read` (default) | List files, read files, get users, view notifications | `NEXTCLOUD_MCP_PERMISSIONS=read` |\n| `write` | Everything in `read` + upload files, send messages, create folders | `NEXTCLOUD_MCP_PERMISSIONS=write` |\n| `destructive` | Everything in `write` + delete files, remove shares | `NEXTCLOUD_MCP_PERMISSIONS=destructive` |\n\nIf a tool is called without sufficient permission, it returns a clear error explaining what permission is needed — no silent failures, no accidental deletions.\n\n## Installation\n\n```bash\npip install nc-mcp-server\n```\n\nOr with `pipx` / `uvx` for isolated installation:\n```bash\npipx install nc-mcp-server\n# or\nuvx nc-mcp-server\n```\n\nOr from source:\n```bash\ngit clone https://github.com/cloud-py-api/nc_mcp_server.git\ncd nc_mcp_server\npip install -e .\n```\n\n## Configuration\n\nSet these environment variables:\n\n```bash\n# Required\nexport NEXTCLOUD_URL=https://your-nextcloud.example.com\nexport NEXTCLOUD_USER=your-username\nexport NEXTCLOUD_PASSWORD=your-app-password  # Use an app password, not your main password!\n\n# Optional\nexport NEXTCLOUD_MCP_PERMISSIONS=read  # read (default), write, or destructive\nexport NEXTCLOUD_MCP_RETRY_MAX=3       # max retries on 429/503 (default: 3, 0 to disable)\n```\n\n### Getting an App Password\n\n1. Log into your Nextcloud instance\n2. Go to **Settings** → **Security**\n3. Under \"Devices \u0026 sessions\", create a new app password\n4. Use this password for `NEXTCLOUD_PASSWORD`\n\n## Usage\n\n### With Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nextcloud\": {\n      \"command\": \"nc-mcp-server\",\n      \"env\": {\n        \"NEXTCLOUD_URL\": \"https://your-nextcloud.example.com\",\n        \"NEXTCLOUD_USER\": \"your-username\",\n        \"NEXTCLOUD_PASSWORD\": \"your-app-password\",\n        \"NEXTCLOUD_MCP_PERMISSIONS\": \"read\"\n      }\n    }\n  }\n}\n```\n\n### With Claude Code\n\n```bash\nclaude mcp add nextcloud \\\n  -e NEXTCLOUD_URL=https://your-nextcloud.example.com \\\n  -e NEXTCLOUD_USER=your-username \\\n  -e NEXTCLOUD_PASSWORD=your-app-password \\\n  -e NEXTCLOUD_MCP_PERMISSIONS=read \\\n  -- nc-mcp-server\n```\n\n### As HTTP Server (for containers/remote)\n\n```bash\nnc-mcp-server --transport http\n# Listens on http://0.0.0.0:8100 by default\n```\n\n### Stdio Mode (default)\n\n```bash\nnc-mcp-server\n# Communicates via stdin/stdout — used by MCP clients like Claude Desktop\n```\n\n## Available Tools\n\n### Files\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `list_directory(path)` | read | List files and folders |\n| `get_file(path)` | read | Read a file's content |\n| `search_files(name, mime_type, ...)` | read | Search files by name, type, or path |\n| `upload_file(path, content)` | write | Upload or overwrite a file |\n| `create_directory(path)` | write | Create a new directory |\n| `delete_file(path)` | destructive | Delete a file or directory |\n| `move_file(source, destination)` | destructive | Move or rename a file |\n\n### Users\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `get_current_user()` | read | Get current user info |\n| `list_users(search, limit)` | read | List/search users |\n| `get_user(user_id)` | read | Get specific user details |\n\n### Notifications\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `list_notifications()` | read | List all notifications |\n| `dismiss_notification(id)` | write | Dismiss a single notification |\n| `dismiss_all_notifications()` | write | Dismiss all notifications |\n\n### Activity\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `get_activity(filter, sort, limit, since)` | read | View recent activity with filtering and pagination |\n\n### Talk\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `list_conversations()` | read | List all Talk conversations |\n| `get_conversation(token)` | read | Get conversation details |\n| `get_messages(token, ...)` | read | Get messages from a conversation |\n| `get_participants(token)` | read | List participants in a conversation |\n| `send_message(token, message)` | write | Send a message to a conversation |\n| `create_conversation(name, ...)` | write | Create a new conversation |\n| `delete_message(token, id)` | destructive | Delete a message |\n| `leave_conversation(token)` | destructive | Leave a conversation |\n\n### Talk Polls\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `get_poll(token, poll_id)` | read | Get poll details and results |\n| `create_poll(token, question, options)` | write | Create a poll in a conversation |\n| `vote_poll(token, poll_id, options)` | write | Vote on a poll |\n| `close_poll(token, poll_id)` | write | Close a poll |\n\n### Comments\n\n| Tool | Permission | Description |\n|------|-----------|-------------|\n| `list_comments(path, ...)` | read | List comments on a file |\n| `add_comment(path, message)` | write | Add a comment to a file |\n| `edit_comment(path, comment_id, message)` | write | Edit a comment |\n| `delete_comment(path, comment_id)` | destructive | Delete a comment |\n\n### Coming Soon\n\n- **Shares** — manage file shares\n- **Trashbin** — view and restore deleted files\n- **File Versions** — list and restore file versions\n- **Calendar** — events via CalDAV\n- **Contacts** — contacts via CardDAV\n- **Deck** — boards and cards\n- **Notes** — manage notes\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/cloud-py-api/nc_mcp_server.git\ncd nc_mcp_server\npython3 -m venv venv \u0026\u0026 source venv/bin/activate\npip install -e \".[dev]\"\n\n# Run tests\npytest                              # Unit tests\npytest tests/integration/ -v        # Integration tests (needs running Nextcloud)\n\n# Lint \u0026 type check\nruff check . \u0026\u0026 ruff format --check .\npyright\n```\n\n### Integration Tests\n\nIntegration tests run against a real Nextcloud instance. Set the environment variables and run:\n\n```bash\nexport NEXTCLOUD_URL=http://localhost:8080\nexport NEXTCLOUD_USER=admin\nexport NEXTCLOUD_PASSWORD=admin\npytest tests/integration/ -v -m integration\n```\n\nCI automatically runs integration tests against Nextcloud 32 and 33 Docker containers.\n\n## About This Project\n\nThis 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:\n\n- High-level design decisions\n- Code review of pull requests\n- Resolving architectural questions\n\nThe goal is to explore how far autonomous AI development can go in building production-quality, well-tested software.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-py-api%2Fnc_mcp_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-py-api%2Fnc_mcp_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-py-api%2Fnc_mcp_server/lists"}