Nextcloud MCP Setup Guide: Connect AI to Your Files

Nextcloud MCP lets AI assistants like Claude read your files, calendar, and notes directly from your Nextcloud instance. This guide walks you through setup, compares the three main approaches, and shows you how to scope access safely.

What is Nextcloud MCP?

MCP--Model Context Protocol--is a standard for AI assistants to request data from external systems. Nextcloud MCP exposes your Nextcloud data as structured tools that Claude, ChatGPT, n8n, or other AI platforms can call.

Real example: Instead of copying and pasting a calendar event into an AI to convert it into a task, you ask Claude "Create a Deck task from my calendar event on Friday." Claude calls the Nextcloud MCP server, fetches the event, and creates the task--all without you touching the UI.

Nextcloud MCP supports 110+ tools across 12 apps: Notes, Calendar, Contacts, Files, Deck, Cookbook, Tables, Talk, News, Mail, and Collectives. You're not exporting data--you're granting the AI temporary, scoped access to live Nextcloud APIs.

The main advantage over direct WebDAV mounting is performance. A WebDAV mount on your client pulls the entire file tree at startup; MCP calls specific endpoints on demand. For large Nextcloud instances (100+ GB), this difference is noticeable. You get faster queries and less network overhead.

Three Ways to Connect Nextcloud to AI

You have three implementation paths. Each has tradeoffs.

MCP for Cloud (v1.2.5, updated 4 days ago) is the simplest entry point. Install it from your Nextcloud app store, generate an app password, and paste the credentials into your Claude Desktop config. No separate infrastructure. The MCP runs inside Nextcloud.

Trade-off: Single-user and read-only for most operations. If you need write access or multi-user setups, this won't cover it.

MCP Connector (v0.7.1, updated 2 days ago) is the native app for teams. It uses Nextcloud's OAuth login flow instead of app passwords, so each user can connect with their own account. Permissions are enforced--a user only sees files they have access to.

Trade-off: Setup is more complex. You configure OAuth scopes in Nextcloud's admin settings, then distribute a config link to each team member. It works well for 5-50 person teams.

External MCP Server is the community's solution for full flexibility. The most popular is cbcoutinho/nextcloud-mcp-server (405 GitHub stars). You run it as a Docker container or local Python service. It exposes all 110+ Nextcloud tools and supports both single-user (app password) and multi-user (OAuth) authentication.

Trade-off: You own the infrastructure. If it breaks, you fix it. You need Docker or Python installed. But you get the full feature set and can customize the tool list per AI client.

Decision: For most solo founders or small teams, start with MCP for Cloud. It takes 10 minutes and requires no infrastructure. If you need multi-user access or write operations, jump to the external server. MCP Connector sits in the middle--useful if you're already managing Nextcloud and want native integration.

Before You Start: Prerequisites and App Passwords

You'll need three things.

First, a Nextcloud instance. This can be self-hosted (your own server), managed (via a hosting provider), or cloud-based (Nextcloud.Com). If you don't have one yet, check out /hosting/nextcloud to explore managed options. Self-hosted or managed instances give you full control and better performance than public cloud alternatives.

Second, an app password. Never use your main Nextcloud password with an AI assistant--that grants full access to your account if the AI tool is compromised. Instead, create a limited app password.

Here's how: Log into Nextcloud, go to Settings (top right) > Security > Devices & client credentials. Click "Create new app password." Give it a name like "Claude MCP" and copy the generated token. This app password can be revoked anytime without changing your main password. If you're using MCP Connector or an external server with multi-user setup, each user follows the same steps. There's no shared credential risk.

Third, know which AI client you're connecting. Claude Desktop is the most popular target (covered below). ChatGPT uses a different config stored in ChatGPT settings, not a file. n8n has its own MCP integration. Each has a different setup flow, but the Nextcloud side is identical--you're always providing the same app password and instance URL.

Step-by-Step: Set Up a Local Nextcloud MCP Server

This section covers the external MCP server approach (cbcoutinho). It's more setup than MCP for Cloud, but gives you the most features and most control.

Option A: Running with uvx (no installation required).

uvx is a Python tool runner that fetches and executes packages without installing them. If you have Python 3.10+ on your machine, run:

uvx --python 3.10 cbcoutinho/nextcloud-mcp-server

That's it. The server starts and listens on a local socket. You point your AI client to that socket and you're done. This is the fastest path if you're testing.

Option B: Running with Docker.

Docker is better if you want the server to persist or run in the background. Create a docker-compose.yml file and configure it with three environment variables: NEXTCLOUD_URL (the address of your Nextcloud instance), NEXTCLOUD_USERNAME (your Nextcloud username), and NEXTCLOUD_PASSWORD (the app password you created earlier). Set the port mapping to expose 8000, then run docker compose up -d. Now the MCP server is running and accessible at localhost:8000.

Configuring Claude Desktop.

1. Open your Claude Desktop config file: ~/.claude/config.json on Mac/Linux, or C:\Users<YourName>\AppData\Roaming\Claude\config.json on Windows.

2. Add the MCP server under the "mcpServers" section. Use the "nextcloud" server type, set the command to "uvx", and add the args and environment variables. In the environment block, set NEXTCLOUD_URL to your Nextcloud instance address, NEXTCLOUD_USERNAME to your username, and NEXTCLOUD_PASSWORD to the app password you created.

3. Restart Claude Desktop.

4. In Claude, open a new chat and type: "What MCP tools do you have access to?" Claude will list the Nextcloud tools it can call. If the list is empty, check your Nextcloud URL and credentials. Verify the app password has the right permissions and the Nextcloud server is reachable from your machine.

For ChatGPT and n8n:

ChatGPT doesn't run local MCP servers directly (as of November 2026). Instead, you'd use a cloud-hosted MCP proxy (Astrolabe, under development) or run an external HTTP endpoint.

n8n has native MCP support in recent versions. Configure the MCP connector node with your Nextcloud MCP server URL and credentials. Then use n8n nodes to fetch files, create calendar events, and trigger workflows based on Nextcloud data.

Scope and Security: What to Expose and Protect

MCP is an API layer. The more access you grant, the more risk you take on if the AI tool malfunctions or is compromised.

Start read-only. Most use cases (fetching notes, reading files, checking calendar) don't need write access. The MCP server can be configured to block write operations entirely. In the environment variables, set READONLY=true. Now Claude can read but not modify.

If you do grant write access (creating notes, updating tasks), tag sensitive files so they're never exposed. In your Nextcloud MCP server config, specify file patterns to exclude:

EXCLUDED_TAGS=sensitive,confidential,private

Files tagged with those labels won't appear in MCP tool listings. This is the safest approach for mixed-sensitivity data stores.

For multi-user setups, MCP Connector or the external server with OAuth ensures each user only sees their own files. If you're using app passwords (shared credentials), all users have the same access level. That's fine for small teams where everyone needs the same scope, but risky at scale. Use OAuth for enterprise deployments.

Never expose Nextcloud passwords to the internet. If you're running the MCP server externally (not on your local machine), use a VPN or reverse proxy with TLS and authentication. A public, unprotected MCP server endpoint is a data leak.

One more safety check: test the MCP tools in a sandbox first. Ask Claude to fetch a non-sensitive file and describe what it contains. If the output is correct, the connection is working. If Claude returns an error or empty results, verify your app password and Nextcloud URL before expanding scope.

Integration Examples: Real Prompts and Workflows

Claude Desktop:

• Prompt: "What's on my calendar for next Thursday?" Claude fetches your calendar events and returns them as structured text. No copy-paste needed.
• Prompt: "Create a note called 'Meeting Recap' with these points: [list]" Claude creates the note directly in your Nextcloud Notes app.
• Prompt: "Find all PDFs in my Documents folder" Claude lists them with metadata.

n8n Workflows:

• Trigger a daily n8n task that calls your Nextcloud MCP server via the MCP connector node, fetches all events for today, and sends an email digest.
• Poll your Nextcloud Files folder, check for new PDFs, extract text with OCR (if enabled in the MCP server), and save the results to a database.
• Create a task in Deck whenever a new file appears in a specific folder, automating project setup.

Limitations to know: Not all Nextcloud apps are equally supported in all MCP implementations. The external server (cbcoutinho) supports 12 apps and 110+ tools. MCP for Cloud supports fewer (mostly read-only notes and files). Check the app's documentation to see what tools are available before betting your workflow on it.

ChatGPT integration is not yet available for local MCP servers. When it ships, the setup will be similar to Claude, but ChatGPT's version is still in development.

Troubleshooting and Common Issues

"Connection timeout" when Claude tries to fetch data: Verify your Nextcloud URL is reachable from your machine. Use curl or a browser to test connectivity to your Nextcloud instance. If you get a response, the server is up. If timeout, check network connectivity and firewall rules. If your Nextcloud is behind a VPN or corporate proxy, ensure the MCP server has access to it.

"Permission denied" when Claude tries to write: You may have set READONLY=true. Check your MCP server config. Or your app password may lack write permissions. In Nextcloud, go to Settings > Security > Devices & client credentials, find your app password, and confirm it has write scopes (if needed). Regenerate it if scopes are wrong.

"Empty tool list" in Claude: Claude connected but sees no tools. This usually means the app password is wrong or the Nextcloud instance is rejecting the MCP server's requests. Verify credentials, check Nextcloud logs (typically in /var/www/nextcloud/data/nextcloud.log if self-hosted), and restart the MCP server. Test the connection manually using the same credentials.

"I'm running Nextcloud but MCP for Cloud won't install": Some older Nextcloud versions don't support the latest MCP for Cloud app. Check Nextcloud's admin panel for app compatibility warnings. If blocked, either upgrade Nextcloud or use the external server instead.

"I have a large Nextcloud instance (100+ GB) and MCP is slow": Local MCP servers are faster than WebDAV, but if you have thousands of files, initial tool listing can take time. Mitigate by tagging files and configuring exclusions so the server only indexes relevant data. Exclude /Photos and /Archive if you don't need MCP access to them.

If you don't want to manage the MCP server yourself, use managed Nextcloud hosting. A provider handles updates, backups, and performance tuning. You get a stable instance to connect your MCP server to.

Frequently Asked Questions

Q: Should I use an app password or my full Nextcloud password for Nextcloud MCP? Always use an app password. App passwords are scoped--they can expire, be revoked, and have restricted permissions. If an AI tool leaks your password, only that one app password is exposed, not your entire account. Your main password stays safe.

Q: Is Nextcloud MCP secure for sensitive files? Yes, with caveats. MCP respects Nextcloud permissions--if you don't have access to a file, MCP won't expose it. You can further restrict with tags and read-only configs. But MCP is an API; treat it like any API. Don't expose Nextcloud credentials over the internet without TLS and authentication. Use a VPN for external access.

Q: Local MCP server or cloud-hosted? Local is faster and doesn't require external infrastructure. Cloud-hosted (via a managed Nextcloud provider) is easier for teams and doesn't tie the service to your machine. Small teams prefer local. Larger teams prefer cloud-hosted with a managed provider so they don't own the infrastructure.

Q: What's the difference between MCP for Cloud and the external server? MCP for Cloud is a native app--simpler, but limited to single-user and read-only. The external server (cbcoutinho) is standalone--more setup, but supports multi-user and full write access. MCP for Cloud is for testing or simple use cases. External server is for power users.

Q: Can I use Nextcloud MCP with ChatGPT? Not yet. ChatGPT doesn't support local MCP servers as of November 2026. You'd need a cloud-hosted MCP proxy. Claude Desktop is the easiest entry point. Check back in early 2027 for ChatGPT MCP support.

Q: Do I need to upgrade my Nextcloud version to use Nextcloud MCP? MCP for Cloud requires Nextcloud 28+. The external server works with Nextcloud 20+. Check your version in the admin panel. If you're older than 20, upgrade first or consider a managed hosting provider.

Q: What apps does Nextcloud MCP support? The external server supports 110+ tools across 12 apps: Notes, Calendar, Contacts, Files, Deck, Cookbook, Tables, Talk, News, Mail, and Collectives. MCP for Cloud supports a subset, mostly Notes and Files. Check the app store before committing to a specific implementation.

The Bottom Line

Nextcloud MCP is a practical way to give AI assistants access to your files, notes, and calendar without moving data to a third-party cloud service. The three approaches--MCP for Cloud, MCP Connector, and external servers--offer different tradeoffs between simplicity and features.

Start with MCP for Cloud if you're solo and just testing. Move to the external server if you need multi-user access or full control. The setup takes 10-30 minutes depending on which path you choose. Security is strong if you use app passwords, enforce read-only access, and tag sensitive files.

If you're running Nextcloud yourself, this setup works great. If you want Nextcloud without the operational overhead, managed hosting lets you skip the infrastructure headaches. Start at /hosting/nextcloud to explore your options.