nextcloud-connect — scoped NextCloud access for Claude

Small CLI tooling that lets Claude (the assistant) read and write a scoped slice of a NextCloud instance — a shared Deck board for planning and a shared Files folder — using a dedicated, limited service account rather than admin credentials.

Why a dedicated account

A NextCloud app password authenticates as the whole user; it can't be restricted per-app or per-board. Permission is scoped at the user level instead. So access is granted by:

1. Creating a non-admin user (claude).
2. Sharing only specific resources with it (one Deck board, one folder).
3. Generating an app password for that user.

If the on-disk credential ever leaks, the blast radius is just what's been shared with claude, and you revoke a single app password.

Setup

1. Create the user. As admin, create a non-admin NextCloud user, e.g. claude.

2. Generate an app password. App passwords are self-service — you must do this as the claude user (admin can't mint one for another account from the admin UI). Log in as claude → Settings → Security → Create new app password. Copy it (shown once).

3. Share resources with claude:

   • Deck: open the planning board → board menu → Sharing → add claude → grant edit (and manage only if Claude should create or delete stacks/archive the board).
   • Files: open the folder → Share → add claude → read or read/write.

4. Create your config files from the samples (both targets are gitignored):

   cp .nextcloud.env.sample .nextcloud.env
   cp CLAUDE.md.sample CLAUDE.md
   chmod 600 .nextcloud.env          # it's a plaintext secret
   

   Then edit .nextcloud.env with your instance URL, the service account username, and the app password from step 2:

   NEXTCLOUD_URL=https://nextcloud.example.com
   NEXTCLOUD_USER=claude
   NEXTCLOUD_APP_PASSWORD=<the app password from step 2>
   

   And edit CLAUDE.md to fill in your instance-specific details (shared folder names, board ids).

5. Install dependencies: npm install (pulls webdav and node-jq).

What this enables Claude to do

• Plan in Deck: list boards, read/create/move/edit/delete stacks and cards on the shared board.
• Work with Files: list directories, read files, upload/update files, create directories, and delete within the shared folder.

What you can ask of Claude

• "What's on the planning board?" / "Add a card to for ."
• "Move to Done." / "Summarize the cards in ."
• "Read <shared-folder>/<file>." / "Save these notes to <shared-folder>/<path>."

Claude only ever sees what's shared with the service account — nothing else on the instance.

Tooling

Copy CLAUDE.md.sample to CLAUDE.md (gitignored) and fill in your instance-specific details. It documents the deck, dav, and jq commands.