nextcloud-mcp

Read-only MCP server for searching a Nextcloud account over WebDAV.

Setup

Requires Node.js 20 or newer. Create a local environment file and fill it with a Nextcloud app password:

cp .env.example .env
npm install
npm run build

Set NEXTCLOUD_URL, NEXTCLOUD_USERNAME, and NEXTCLOUD_APP_PASSWORD in .env. NEXTCLOUD_PASSWORD is accepted as a fallback, but an app password is recommended. Never commit .env.

MCP client configuration

Use the built executable with an environment block in the MCP client configuration:

{
  "mcpServers": {
    "nextcloud": {
      "command": "node",
      "args": ["/Users/answer.kazuya/coding/nextcloud-mcp/dist/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://nc.answer.mydns.jp/",
        "NEXTCLOUD_USERNAME": "your-user",
        "NEXTCLOUD_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Claude Code and Codex can use the same server. Their user-level configurations are registered locally as follows:

• Claude Code: ~/.claude/settings.json (mcpServers.nextcloud)
• Codex: ~/.codex/config.toml (mcp_servers.nextcloud)

Both configurations launch Node with --env-file and therefore keep the Nextcloud credentials in this project's ignored .env file.

Alternatively, run the server from the project directory so it loads .env:

npm start

Tools

• search_nextcloud: case-insensitive recursive filename and folder-name search. Defaults to depth 8 and returns partial results when bounded.
• reindex_nextcloud: rebuild the local Nextcloud SQLite index and detect new or removed files.
• get_nextcloud_status: show local Nextcloud index progress.
• get_nextcloud_metadata: WebDAV metadata for a file or folder.
• get_nextcloud_link: authenticated browser link, using the Nextcloud file ID when available.
• search_nas: recursive filename and folder-name search in the mounted NAS share. Defaults to depth 8 and returns partial results when bounded.
• reindex_nas: rebuild the local NAS SQLite index and detect new or removed files.
• get_nas_metadata: metadata for a mounted NAS file or folder.
• get_nas_link: a local file:// link for a mounted NAS path.
• get_nas_status: mounted-state check and connection instructions.

The NAS integration searches the locally mounted share configured by NAS_MOUNT_PATH (for example /Volumes/share on macOS or Z:\\share on Windows). Connect or map the share using the operating system first. It does not store or handle NAS credentials, and NAS tools fail when the share is not mounted. Each PC can use its own path in its local .env file. The server does not expose upload, move, delete, or any other write operation.

The server starts building a local SQLite index in the background. Later searches use the index and are fast. The first search may report that indexing is still in progress; retry after it completes. The index refreshes automatically every NAS_INDEX_REFRESH_MS milliseconds (default 5 minutes), so newly added files appear after the next refresh. Use reindex_nas to start an immediate background update. The index file is local and can be placed with NAS_INDEX_PATH.

Nextcloud search uses a separate local SQLite index. It is built in the background when the server starts, and rows become searchable as they are discovered. get_nextcloud_status shows the indexed file count while it builds. New and removed files are picked up on the next refresh (default 5 minutes) or immediately after reindex_nextcloud. Configure its location with NEXTCLOUD_INDEX_PATH.

For large shares, pass a narrower path (for example 請求書). Search responses include truncated and scannedDirectories so a caller can tell when a bounded scan stopped before exhausting the tree.

When the share is not mounted, NAS tools return an actionable instruction. On macOS, NAS_CONNECT_URL can provide an open 'afp://server/share' command. On Windows and Linux, map or mount the share using the operating system, then set the resulting local path in NAS_MOUNT_PATH. The MCP does not mount shares silently or store NAS credentials.

Roadmap

Full-text search for PDF and Office documents, then a local search index.