Chris CoutinhoandClaude Opus 4.7
8cd3092e87
The Postgres backend hit a hard crashloop in production deployments
where the MCP server runs under anyio TaskGroups with multiple
concurrent background tasks (`vector.oauth_sync.user_manager_task`,
processors, etc.) alongside the request-path code. Symptom in the
pod logs:
RuntimeError: Task <Task pending name='nextcloud_mcp_server.vector.oauth_sync.user_manager_task'>
got Future <Future pending cb=[BaseProtocol._on_waiter_completed()]>
attached to a different loop
followed seconds later by
RuntimeError: Event loop is closed
while SQLAlchemy's pool tries to clean up the failed connection.
The event loop becomes increasingly unresponsive as asyncpg
protocol Futures pile up holding references to closed loops; the
`/health/live` endpoint eventually misses its probe window and
the kubelet SIGKILLs the pod (exitCode 137), restart-looping the
backend.
Root cause: the engine was built with the default
`AsyncAdaptedQueuePool` (`pool_size=2, max_overflow=5`) and
`pool_pre_ping=True`. asyncpg connection objects are bound to the
event loop they were created on. When the process holds a
singleton engine and tasks running under different anyio
TaskGroups check out connections from that pool, the pre-ping
probe runs on a cached connection whose underlying transport
references a different loop's selector → cross-loop access →
crash.
Switch to `NullPool` — one fresh asyncpg connection per
`engine.connect()`, no caching, no cross-loop bookkeeping to get
wrong. asyncpg connection setup is ~5 ms over LAN and a single
round-trip in the local-Postgres case, so the throughput cost is
negligible for the MCP server's traffic shape (low concurrency,
bursty per-user requests). This matches what the SQLite branch
already does (see `initialize()`) and what Alembic's `env.py`
uses for migrations, so the codebase is now consistent across
all backends.
`DATABASE_POOL_SIZE` / `DATABASE_MAX_OVERFLOW` config knobs are
preserved for backward compatibility but no longer affect the
Postgres engine. The validators in `config.py` continue to
reject values < 1 / < 0, so misconfigured deploys still fail
loudly. A follow-up could mark them deprecated in
`docs/configuration.md`; out of scope here.
Discovered while smoke-testing the per-tenant Postgres flow in
Astrolabe Cloud (every-tenant pod fresh-provisions a database
via the ADR-026 backend → hits this crashloop within ~5 min of
the first MCP-routed request).
Refs:
- ADR-026 § "Concurrency model and pool sizing" (the original
QueuePool rationale, now superseded by this finding)
- nextcloud_mcp_server/alembic/env.py (NullPool for migrations)
- SQLAlchemy docs: NullPool is the documented choice when
connection objects don't survive across the lifecycle of the
pool's logical "owner" (here: the event loop)
Verified:
- `uv run ruff check nextcloud_mcp_server/auth/storage.py` clean
- `uv run pytest tests/unit/test_*storage*.py` → 29 passed
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nextcloud MCP Server
A production-ready MCP server that connects AI assistants to your Nextcloud instance.
Enable Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language conversations.
This is a dedicated standalone MCP server designed for external MCP clients like Claude Code and IDEs. It runs independently of Nextcloud (Docker, VM, Kubernetes, or local) and provides deep CRUD operations across Nextcloud apps.
Note
Looking for AI features inside Nextcloud? Nextcloud also provides Context Agent, which powers the Assistant app and runs as an ExApp inside Nextcloud. See docs/comparison-context-agent.md for a detailed comparison of use cases.
Tip
Don't want to self-host? Astrolabe Cloud is a managed hosting service for this MCP server, aimed at users and teams who want advanced features like background sync and semantic search without operating the infrastructure themselves. The service is currently under development — sign up on the landing page to join the early-adopter list.
Quick Start
Run the server locally with uvx (no installation required):
NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
NEXTCLOUD_USERNAME=your_username \
NEXTCLOUD_PASSWORD=your_app_password \
uvx nextcloud-mcp-server run --transport stdio
Or add it directly to your MCP client configuration (e.g. claude_desktop_config.json or .claude/settings.json):
{
"mcpServers": {
"nextcloud": {
"command": "uvx",
"args": ["nextcloud-mcp-server", "run", "--transport", "stdio"],
"env": {
"NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
"NEXTCLOUD_USERNAME": "your_username",
"NEXTCLOUD_PASSWORD": "your_app_password"
}
}
}
}
Tip
Generate an app password in Nextcloud under Settings > Security > Devices & sessions instead of using your login password.
Docker
For full features including semantic search, run with Docker:
docker run -p 127.0.0.1:8000:8000 --rm \
-e NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
-e NEXTCLOUD_USERNAME=your_username \
-e NEXTCLOUD_PASSWORD=your_app_password \
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
Then connect your MCP client (Claude Desktop, IDEs, mcp dev, etc.) to http://127.0.0.1:8000/mcp.
For Kubernetes, see cbcoutinho/helm-charts. For other deployment options and Compose profiles, see docs/installation.md.
Key Features
- 110+ MCP Tools - Comprehensive API coverage across 10 Nextcloud apps
- MCP Resources - Structured data URIs for browsing Nextcloud data
- Semantic Search (Experimental) - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama)
- Document Processing - OCR and text extraction from PDFs, DOCX, images with progress notifications
- Flexible Deployment - Docker, Kubernetes (Helm chart), VM, or local installation
- Production-Ready Auth - Basic Auth with app passwords; multi-user via Login Flow v2 — MCP clients authenticate via OAuth, the server handles Nextcloud app passwords transparently
- Tag-Based File Exclusion - Hide sensitive files/folders from MCP file tools by tagging them with a configured Nextcloud system tag (
EXCLUDED_TAGS). See docs/configuration.md - Multiple Transports - streamable-http (default) and stdio
Supported Apps
| App | Tools | Capabilities |
|---|---|---|
| Notes | 7 | Full CRUD, keyword search, semantic search |
| Calendar | 20+ | Events, todos (tasks), recurring events, attendees, availability |
| Contacts | 8 | Full CardDAV support, address books |
| Files (WebDAV) | 12 | Filesystem access, OCR/document processing |
| Deck | 15 | Boards, stacks, cards, labels, assignments |
| Cookbook | 13 | Recipe management, URL import (schema.org) |
| Tables | 5 | Row operations on Nextcloud Tables |
| Sharing | 10+ | Create and manage shares |
| News | 8 | Feeds, folders, items, feed health monitoring |
| Collectives | 16 | Full CRUD on collectives, pages, and tags |
| Talk (spreed) | 6 | List conversations, read/post messages, mark as read, list participants |
| Semantic Search | 2+ | Vector search for Notes, Files, News items, and Deck cards (experimental, opt-in, requires infrastructure) |
Want to see another Nextcloud app supported? Open an issue or contribute a pull request!
Authentication
The MCP server authenticates to Nextcloud using app-specific passwords (Basic Auth). Three deployment modes are supported:
| Mode | Best for |
|---|---|
| Single-User (BasicAuth) | Personal use, development, single-user deployments |
| Multi-User (BasicAuth pass-through) | Multi-user setups where clients send credentials via Authorization header |
| Multi-User (Login Flow v2) | Multi-user / hosted deployments — clients authenticate to the MCP server via OAuth, and the server obtains a per-user app password from Nextcloud and uses it transparently |
OAuth-direct-to-Nextcloud is no longer supported (it required upstream patches to user_oidc that were never merged). Login Flow v2 replaces it for multi-user deployments and works with stock Nextcloud.
See docs/authentication.md for setup instructions.
Semantic Search
An experimental RAG pipeline that lets MCP clients find Nextcloud content by meaning rather than keywords — a query for "car" also surfaces notes about "vehicle" or "transportation". Disabled by default (ENABLE_SEMANTIC_SEARCH=false); requires a vector database and embedding service. See docs/semantic-search-architecture.md and docs/configuration.md.
Tip
Don't want to run Qdrant and an embedding service? Astrolabe Cloud (under development) provides semantic search and background sync as a managed service.
Documentation
- Installation — Docker, Compose profiles, local, VM
- Configuration — Environment variables, document processing, semantic search setup
- Authentication — Basic Auth, Login Flow v2
- Running the Server — Start, manage, troubleshoot
- App Documentation — Per-app guides (Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables)
- Semantic Search Architecture + Vector Sync UI
- Login Flow v2 — recommended multi-user setup (architecture, env vars, scope reference, troubleshooting)
- Troubleshooting · Comparison with Context Agent
Contributing
Contributions are welcome!
- Report bugs or request features: GitHub Issues
- Submit improvements: Pull Requests
- Development guidelines: CLAUDE.md
Security
Found a security issue? Do not open a public GitHub issue. Use GitHub's private vulnerability reporting, or email security@astrolabecloud.com if you can't use GitHub. See SECURITY.md for details.
License
This project is licensed under the AGPL-3.0 License. See LICENSE for details.