Nextcloud MCP Server

A Model Context Protocol (MCP) server that integrates with Nextcloud to provide access to:

• Tasks (via CalDAV)
• Calendar Events (via CalDAV)
• Notes (via Notes API)
• Emails (via Mail API)

Features

Tasks

• ✅ Get tasks (filter by status: all/open/completed)
• ✅ Create new tasks with due dates and priorities
• ✅ Update tasks (mark complete, change summary, etc.)

Calendar

• ✅ Get calendar events with date range filtering
• ✅ Query one, many, or all VEVENT calendars automatically
• ✅ Discover available calendars and supported components
• ✅ 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 configured

Prerequisites

1. Nextcloud Instance (any recent version with CalDAV support)

2. Required Nextcloud Apps:

   • Tasks (for task management)
   • Calendar (for events)
   • Notes (for note-taking)
   • Mail (optional, for email access)

3. App Password: Generate in Nextcloud Settings > Security > Devices & sessions

Installation

npm install
npm run build

Configuration

1. Copy the environment template:

cp .env.example .env

2. Edit .env with your Nextcloud credentials:

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

⚠️ Important: Always use an app password, never your main Nextcloud password!

Usage

Testing Locally

# Development mode (auto-reload)
npm run dev

# Production mode
npm run start

Using with Claude Desktop

Add this to your Claude Desktop configuration file:

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

{
  "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"
      }
    }
  }
}

Or use the development version with tsx:

{
  "mcpServers": {
    "nextcloud": {
      "command": "npx",
      "args": ["-y", "tsx", "/path/to/nextcloud-mcp/src/index.ts"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server.

Available Tools

Once connected, Claude can use these tools:

Tasks

• get_tasks - Retrieve tasks (filter by status, limit results)
• create_task - Create new task with summary, description, due date, priority
• update_task - Update existing task (mark complete, change details)

Calendar

• list_calendars - List available calendars (name, href, components)
• get_calendar_events - Get events in date range across selected calendars
• create_calendar_event - Create new event with details

get_calendar_events supports:

• startDate / endDate (YYYY-MM-DD)
• calendar (single calendar name or href)
• calendars (array of names/hrefs)
• includeAllCalendars (default true, queries all VEVENT calendars when no selectors are provided)
• limit

Notes

• get_notes - List all notes
• create_note - Create new note with markdown
• get_note_content - Get full content of specific note

Email

• get_emails - Retrieve recent emails from inbox

Example Prompts for Claude

Once the MCP server is connected, you can ask Claude:

"Show me my open tasks for this week"
"Create a task to review the Q4 report, due next Friday"
"What meetings do I have tomorrow?"
"Create a calendar event for team standup tomorrow at 10am"
"Show me my recent notes"
"Create a note about the meeting outcomes"
"What are my latest emails?"

Troubleshooting

Connection Issues

• Verify your Nextcloud URL (use HTTPS, no trailing slash)
• Ensure app password is correct
• Check that required apps (Tasks, Calendar, Notes) are installed

CalDAV Issues

• Use list_calendars to discover calendar names/hrefs from your server
• Set DEBUG_NEXTCLOUD_MCP=1 to log CalDAV requests and parsing details
• Default task list name is still tasks for task operations

Debugging with curl

List calendars with PROPFIND:

curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  -X PROPFIND \
  -H "Depth: 1" \
  -H "Accept: application/xml" \
  -H "Content-Type: application/xml; charset=utf-8" \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
  <d:prop>
    <d:displayname />
    <d:resourcetype />
    <c:supported-calendar-component-set />
  </d:prop>
</d:propfind>' \
  "$NEXTCLOUD_URL/remote.php/dav/calendars/$NEXTCLOUD_USERNAME/"

Query events with REPORT:

curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  -X REPORT \
  -H "Depth: 1" \
  -H "Accept: application/xml" \
  -H "Content-Type: application/xml; charset=utf-8" \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<c:calendar-query xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:d="DAV:">
  <d:prop>
    <d:getetag />
    <c:calendar-data />
  </d:prop>
  <c:filter>
    <c:comp-filter name="VCALENDAR">
      <c:comp-filter name="VEVENT">
        <c:time-range start="20260201T000000Z" end="20260301T000000Z"/>
      </c:comp-filter>
    </c:comp-filter>
  </c:filter>
</c:calendar-query>' \
  "$NEXTCLOUD_URL/remote.php/dav/calendars/$NEXTCLOUD_USERNAME/personal/"

Email Issues

• Ensure Nextcloud Mail app is installed and configured
• Check that at least one email account is set up
• Account ID defaults to 0 (first account)

Debug Mode

Check the MCP server logs in Claude Desktop:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

API Endpoints Used

• CalDAV: /remote.php/dav/calendars/{username}/
• Notes: /index.php/apps/notes/api/v1/notes
• Mail: /index.php/apps/mail/api/

Security Notes

• 🔐 Always use app passwords, never your main password
• 🔒 Store credentials securely (environment variables, not in code)
• 🛡️ Use HTTPS for your Nextcloud instance
• 🔑 Limit app password scopes if possible in Nextcloud

Customization

Calendar Selection

Use list_calendars and pass calendar / calendars to get_calendar_events to target specific calendars by name or href.

Changing Task List Names

// Default tasks list
const caldavPath = `/remote.php/dav/calendars/${this.config.username}/tasks/`;

// For a different task list
const caldavPath = `/remote.php/dav/calendars/${this.config.username}/personal-tasks/`;

Development

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run watch  # In one terminal
npm run dev    # In another terminal

# Build for production
npm run build

License

MIT

Contributing

Feel free to submit issues and pull requests for:

• Additional Nextcloud integrations
• Bug fixes
• Documentation improvements
• Feature enhancements

Resources

• MCP Documentation
• Nextcloud API Documentation
• CalDAV Documentation