# Using Nextcloud with Claude

Claude, our AI assistant, can work with your Nextcloud for you: mail, files, calendar, contacts, Deck, Talk, Notes and Nextcloud Office documents. It does this through the **"nextcloud-api"** skill, which calls Nextcloud's own API directly. This page explains the one-time setup and how to use it well.

## What Claude can do with Nextcloud

- **Find mail anywhere.** Ask *"Find everything from EnAccess since September"* and Claude searches every folder of every mail account you have in Nextcloud, not just the newest 100 messages. It tells you which folders it searched.
- **Tidy your inbox.** Move, mark as read or unread, star, or send emails to Trash, in bulk. Claude shows you the list first and only changes anything after you say yes.
- **Files and sharing.** Search, read and summarise files, including spreadsheets and Word documents. Claude can also upload, move and share files after you approve.
- **Calendar and Deck.** *"What's on my calendar this week, and which Deck cards are due before Friday?"*
- **Talk and Notes.** Read conversations and notes. Claude can post a message, but only after you've seen the exact text and approved it.
- **Mail filters.** Set up server-side rules, for example filing the NFE Inverter Monitor alerts into their own folder.

Claude only sees what your own Nextcloud account can see. Anything it changes is done as you.

## One-time setup

The skill is set up for everyone already; the only thing you need to do yourself is create your app password (step 3). In full, you need three things:

1. **Claude on your own computer.** The skill works in the Claude desktop app (Code tab) or in Claude Code, on macOS, Linux or Windows (with WSL or Git Bash). Your app password stays in a file on your computer.
2. **The skill.** It's already set up for everyone in our Claude organisation, so there's nothing to install. If it doesn't show up for you (for example, in a Claude Code setup outside the organisation), download `nextcloud-api.skill` from the attachments on this page (paperclip icon, top right). Open it and click **Save skill**, or unzip it into `~/.claude/skills/`.
3. **Your personal Nextcloud app password**, saved in a private file on your computer:
   1. In a Claude chat, ask something like *"Using Nextcloud, what's on my calendar this week?"*
   2. The first time, Claude creates the file `~/.config/nextcloud-api/credentials.env`, with your Nextcloud username filled in and the password left blank.
   3. In Nextcloud, go to your avatar (top right) → **Personal settings** → **Security** → **Devices & sessions**. Type `claude-api` as the app name and click **Create new app password**. Copy the password. It's only shown once.
   4. Open the file. On a Mac: Finder → **Go → Go to Folder…** → `~/.config/nextcloud-api`, then open `credentials.env` with TextEdit. Paste the password straight after `NEXTCLOUD_APP_PASSWORD=`, with no spaces or quotes, and save.
   5. Tell Claude **"done"**. It will confirm that it can sign in as you.

To revoke access, delete the `claude-api` entry under **Devices & sessions**.

## Keeping your password safe

- **Never paste the app password into a chat**, an email, Matrix, a Library page or a shared document. It only goes in the file on your computer.
- Claude is set up never to show, print or read out the password. It passes the password straight to Nextcloud.
- An app password can be revoked on its own, without changing your normal Nextcloud password. If you think it has been exposed, delete it and create a new one.

## How Claude handles changes

- **Reading is free.** Searching, listing and summarising happen straight away.
- **Changes need your yes.** Before it moves, marks, deletes, shares, sends or posts anything, or changes a setting, Claude shows you what it will do and how many items it affects. It waits for your answer, and an approval covers only what you were shown.
- **"Delete" means Trash.** Emails go to your Trash folder and files go to the Nextcloud trash bin, so everything can be restored. Claude never empties the trash.
- **Claude checks its work.** After a change, it recounts and tells you the actual result, including anything that failed.

## Tips for good results

- **Name the person or organisation** when searching mail, e.g. *"anything involving joscha or enaccess.org"*. Claude finds mail they sent, mail sent to them, and mail where they were copied.
- **Give a date range** (*"since 1 September"*). Searches are much faster with one.
- **Ask what was covered.** Claude should say which folders and dates it searched. If something seems missing, ask it to check other accounts or folders.
- **Topics often live in folder names**, e.g. `Sezibwa Rentals/`. If a file search finds nothing, ask Claude to look inside the folder.
- When you work out a useful routine, such as a weekly calendar and Deck review, add it to the Library so others can use it too.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| "No Nextcloud app password found" | Fill in `NEXTCLOUD_APP_PASSWORD` in `~/.config/nextcloud-api/credentials.env` and save. |
| "File does not exist" when opening the file | The `.config` folder is hidden. Use Finder → Go → Go to Folder…, and make sure you didn't copy a trailing full stop. |
| Error 401 | The app password is wrong or was revoked. Create a new one and update the file. |
| A mail folder shows 0 messages or "not cached" | Claude syncs it automatically. If it still looks wrong, open the folder once in Nextcloud Mail. |
| A mail filter you want isn't available | Sieve filtering is off for that account. It's under Mail → account settings → Sieve server → Enable sieve filter. Claude will ask before turning it on. |
| The mcphub Nextcloud tools return "Invalid request parameters" | That's the separate mcphub connector, not this skill. Use this skill instead, and let Aaron know so mcphub can be checked. |

## For admins

- **Skill:** "nextcloud-api", set up for everyone in Claude under **Organization settings → Plugins & skills**. Updates are made by uploading a new version there. When you do, also replace the attachment on this page, which is kept for manual installs.
- **Local copies:** anyone who installed the skill by hand in `~/.claude/skills/nextcloud-api` should remove that folder, so the organisation's version (and its updates) is the one used.
- **Server:** https://nextcloud.nearlyfreeenergy.com (Nextcloud 34). The skill uses the Mail, WebDAV/CalDAV/CardDAV, OCS (sharing, Talk), Deck, Notes and file-templates APIs.
- **Network:** `*.nearlyfreeenergy.com` must be reachable from wherever Claude runs commands.
- **Why not just mcphub?** mcphub's Nextcloud mail tools cap lists at 100 messages and can't search, move, mark as read or trash mail. The skill does all of that directly and works even when mcphub is down.

*Last reviewed: 20 October 2026 by Aaron Tushabe (skill now set up for the whole organisation)*