nextcloud-mcp

Nextcloud MCP Server

A Model Context Protocol (MCP) server that integrates with Nextcloud to provide access to tasks, calendar, notes, email, files, and Deck boards. Supports both local stdio (Claude Desktop) and remote HTTP/SSE transport (Claude Mobile via a Pi or server deployment).

Features

Tasks

• Get tasks across all lists or a specific list (filter by status: all/open/completed)
• Create new tasks with due dates and priorities
• Update tasks (mark complete, change summary, etc.)
• Discover all available task lists

Calendar

• Get calendar events with date range filtering
• Create new calendar events with details and location

Notes

• Get all notes
• Create new notes with markdown support
• Get specific note content by ID

Email

• Get emails from inbox (requires Nextcloud Mail app)

Files (WebDAV)

• List files and folders with metadata (size, type, last modified)
• Read text file content
• Upload / create or overwrite files
• Create folders
• Move or rename files and folders

Deck (Kanban)

• List all boards
• Get a full board view — all stacks (columns) and cards with assignees and labels
• Create cards in a stack
• Update card title, description, or due date
• Move cards between columns

Prerequisites

1. Nextcloud instance (any recent version with CalDAV support)
2. Required Nextcloud apps:

• Tasks — task management
• Calendar — events
• Notes — note-taking
• Deck — Kanban boards
• Mail — optional, for email access

1. App password: generate in Nextcloud Settings > Security > Devices & sessions

Installation

npm install
npm run build

Configuration

Set these environment variables (or put them in a .env file for local dev):

NEXTCLOUD_URL=https://your-nextcloud.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password

# HTTP/SSE mode (omit for stdio)
MCP_TRANSPORT=http
MCP_PORT=3000
MCP_AUTH_TOKEN=your-secret-token

⚠️ Always use an app password, never your main Nextcloud password.

Transport modes

stdio (default) — Claude Desktop, local

The server is launched as a subprocess by Claude Desktop.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "nextcloud": {
      "command": "node",
      "args": ["/path/to/nextcloud-mcp/build/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}

HTTP/SSE — Raspberry Pi or server deployment

Set MCP_TRANSPORT=http and the server listens on MCP_PORT (default 3000).

Endpoints:

• GET /sse — SSE connection
• POST /messages?sessionId=… — inbound messages
• GET /health — health check (no auth required)

systemd service

Create /etc/systemd/system/nextcloud-mcp.service:

[Unit]
Description=Nextcloud MCP Server
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/nextcloud-mcp
ExecStart=/usr/bin/node build/index.js
Restart=on-failure
Environment=MCP_TRANSPORT=http
Environment=MCP_PORT=3000
Environment=MCP_AUTH_TOKEN=your-secret-token
Environment=NEXTCLOUD_URL=https://your-nextcloud.com
Environment=NEXTCLOUD_USERNAME=your-username
Environment=NEXTCLOUD_PASSWORD=your-app-password

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now nextcloud-mcp

Apache reverse proxy

Add a location block to your existing SSL vhost. SSE requires buffering to be disabled or the event stream stalls.

<Location /mcp/>
    ProxyPass        http://localhost:3000/ flushpackets=on
    ProxyPassReverse http://localhost:3000/

    # Required for SSE — flush packets immediately rather than buffering
    SetEnv           proxy-nokeepalive 1
    SetEnv           proxy-initial-not-buffered 1
</Location>

Enable the required modules if not already active:

sudo a2enmod proxy proxy_http
sudo systemctl reload apache2

Connecting clients

Claude Desktop (local LAN, no Apache needed): ``json { "mcpServers": { "nextcloud": { "url": "http://raspberrypi.local:3000/sse", "headers": { "Authorization": "Bearer your-secret-token" } } } } ``

Claude Mobile (via Apache/HTTPS):

Add as a remote integration in the Claude app: `` URL: https://yourdomain.com/mcp/sse Authorization: Bearer your-secret-token ``

Available tools

Tasks

| Tool | Description | |------|-------------| | get_task_lists | Discover all VTODO-capable lists | | get_tasks | Retrieve tasks; filter by list, status, limit | | create_task | Create task with summary, description, due date, priority | | update_task | Update status, summary, or percent complete |

Calendar

| Tool | Description | |------|-------------| | get_calendar_events | Get events in a date range | | create_calendar_event | Create event with title, times, description, location |

Notes

| Tool | Description | |------|-------------| | get_notes | List all notes | | create_note | Create note with title, content, category | | get_note_content | Get full content of a note by ID |

Email

| Tool | Description | |------|-------------| | get_emails | Get recent inbox emails |

Files

| Tool | Description | |------|-------------| | list_files | List folder contents with metadata | | get_file | Read a text file's content | | upload_file | Create or overwrite a file | | create_folder | Create a new directory | | move_file | Move or rename a file or folder |

Deck

| Tool | Description | |------|-------------| | get_deck_boards | List all boards | | get_deck_board | Full board view with stacks and cards | | create_deck_card | Add a card to a stack | | update_deck_card | Edit card title, description, or due date | | move_deck_card | Move card to a different column |

Example prompts

"Show me my open tasks"
"Create a task to review the Q4 report, due next Friday"
"What meetings do I have this week?"
"List the files in my Documents folder"
"Read the file Projects/notes.md"
"Show me the boards in Deck"
"Move the 'Fix login bug' card to In Progress"
"What are my latest emails?"

Troubleshooting

Connection issues

• Use HTTPS for your Nextcloud URL, no trailing slash
• Verify the app password is correct
• Ensure required apps are installed in Nextcloud

SSE stream not working through Apache

• Confirm proxy_http module is enabled
• Ensure ProxyBuffering off is set — without this, events are buffered and clients appear to hang

Deck cards not showing

• get_deck_board fetches stacks in a separate request from boards — ensure the Deck app is installed and the board ID is correct

CalDAV issues

• Task list and calendar names are case-sensitive and must match your Nextcloud setup
• Default calendar is personal; use get_task_lists to discover list IDs

Email issues

• Nextcloud Mail app must be installed and have at least one account configured
• Account ID defaults to 0 (first account)

Debug logs

• macOS: ~/Library/Logs/Claude/mcp*.log
• HTTP mode: stdout/stderr from the systemd service (journalctl -u nextcloud-mcp -f)

Security

• Always use app passwords, never your main Nextcloud password
• Set MCP_AUTH_TOKEN whenever the server is reachable over a network
• Use HTTPS (via your existing Apache SSL vhost) for internet-facing deployments
• Store credentials in environment variables or the systemd unit file, not in code

API endpoints used

• CalDAV: /remote.php/dav/calendars/{username}/
• WebDAV: /remote.php/dav/files/{username}/
• Notes: /index.php/apps/notes/api/v1/
• Mail: /index.php/apps/mail/api/
• Deck: /ocs/v2.php/apps/deck/api/v1.0/

License

MIT