Nextcloud MCP Server

A custom MCP (Model Context Protocol) server that gives Claude the ability to list, read, write, create folders in, delete, and search files in a self-hosted Nextcloud instance over WebDAV.

Works with Claude Desktop out of the box (local/stdio), with an optional HTTP/Docker version for remote setups.

Tools it exposes

File operations

Tool	Description
list_files(path)	List files/folders at a path
read_file(path)	Read a text file's contents
write_file(path, content)	Create or overwrite a text file
create_folder(path)	Create a folder
delete_item(path)	Delete a file or folder (permanent beyond trash retention)
search_files(query, path)	Recursively search filenames

Obsidian vault operations

These understand Markdown notes as an Obsidian vault, not just plain files — parsing frontmatter, [[wikilinks]], and #tags the way Obsidian itself would. Built for the common setup where your vault syncs through Nextcloud (via the Nextcloud desktop client) rather than living in a local-only folder, which is what most Obsidian-focused MCP servers assume.

Tool	Description
get_frontmatter(path)	Read a note's YAML frontmatter as JSON
update_frontmatter(path, fields)	Merge new fields into a note's frontmatter without touching the body
list_by_tag(tag, path)	Find every note carrying a tag, frontmatter or inline
get_backlinks(note, path)	Find every note that links to a given note
resolve_link(link_text, path)	Resolve a wikilink to the actual file it points to, fuzzy-matched like Obsidian does
graph_neighbors(note, path, depth)	List notes connected to a given note by links, out to N hops

Which version should I use?

• server_stdio.py — Recommended for most people. Claude Desktop launches this locally as a subprocess and it talks to Nextcloud over your LAN/Tailscale/VPN directly. No public exposure needed.
• server.py — An HTTP version for running as a standalone service (e.g. in Docker). Only needed if you want to add this as a remote custom connector in Claude — which requires the server to be reachable via a public HTTPS URL (e.g. behind a Cloudflare Tunnel or reverse proxy), since custom connectors are reached from Anthropic's cloud infrastructure, not your local device.

Setup — Claude Desktop (local, recommended)

1. Clone this repo and install dependencies for the Python interpreter Claude Desktop will use:

   git clone https://github.com/yourusername/nextcloud-mcp.git
   cd nextcloud-mcp
   pip install -r requirements.txt
   

2. Create a Nextcloud app password: in Nextcloud, go to Settings → Security → App passwords, create one (e.g. named claude-mcp), and save it somewhere safe. Don't use your real account password.

3. Edit your Claude Desktop config file (claude_desktop_config.json):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   Copy the contents of claude_desktop_config.example.json, and update:

   • args to the absolute path of server_stdio.py on your machine
   • NEXTCLOUD_URL, NEXTCLOUD_USER, NEXTCLOUD_PASSWORD to your own values

4. Fully restart Claude Desktop (quit from the system tray/menu bar, not just close the window).

You should now see Nextcloud tools available in your conversations.

Setup — HTTP/Docker (remote custom connector)

1. Copy .env.example to .env and fill in your Nextcloud URL, username, and app password.
2. Build and run:

   docker compose up -d --build
   

3. Expose the container's port (default 8765) via a public HTTPS URL — for example a Cloudflare Tunnel, Tailscale Funnel, or a reverse proxy with TLS. A private LAN address alone will not be reachable by Claude's custom connector setup.
4. In Claude, add a custom connector pointing at https://your-public-url/mcp.

Troubleshooting

• ModuleNotFoundError: No module named 'mcp.server.fastmcp' — you likely installed mcp version 2.x, which restructured the package. This project pins mcp>=1.6.0,<2.0.0 in requirements.txt; reinstall with that constraint.
• ModuleNotFoundError for requests or mcp even after installing — if you have multiple Python versions installed, make sure you install dependencies against the exact interpreter Claude Desktop launches (check Claude Desktop's MCP logs for the interpreter path if unsure).
• Server doesn't show up in Claude Desktop — make sure you fully restarted the app after editing the config, and double-check the args path is absolute and correct for your OS.

Security notes

• Always use a scoped Nextcloud app password, not your real account password — revoke it anytime via Settings → Security → Devices & Sessions.
• delete_item() is permanent beyond Nextcloud's trash retention. Use with care, especially since Claude can call it directly during a conversation.
• Never commit your .env file or real credentials — .gitignore is already set up to exclude .env.

License

MIT — see LICENSE.