Skip to main content
Glama

tasks-mcp

A Model Context Protocol server for Nextcloud Tasks — exposes task lists, tasks, subtasks and tags to Claude and any MCP-compatible client.

How it works

The Nextcloud Tasks app ships no REST or OCS API. It is a Vue front end over Nextcloud's existing calendar backend, so every task is an iCalendar VTODO and every operation is CalDAV: PROPFIND to discover the calendar home, REPORT to query, PUT and DELETE on individual .ics objects.

That makes this server structurally different from the Notes and Collectives ones. It carries its own namespace-aware XML reader for multistatus responses — prefixes are chosen per response by sabre/dav, propstat blocks are per-status, and calendar-data arrives as XML-escaped iCalendar, none of which survives a regex. ical.js handles the iCalendar layer.

Details and the behaviours that are not in the published specs are in ENDPOINTS.md.

Related MCP server: nextcloud-tasks-mcp

Tools exposed (11)

  • Tasks: list_tasks, get_task, create_task, update_task, delete_task, move_task

  • Completion: complete_task, uncomplete_task

  • Organisation: list_task_lists, list_tags

  • Other: ping

Every tool declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can distinguish a read from an irreversible delete without parsing descriptions.

Updates never clobber what they do not touch

update_task edits the parsed VTODO in place rather than rebuilding it. Recurrence rules, reminders, attendees, and any X-property written by DAVx5, Apple Reminders or Thunderbird pass through a write untouched — nothing removes what it does not recognise. This is what makes the server safe to point at a task list you also sync to a phone.

Only the fields you pass are changed. Passing null clears a field, which is a different request from omitting it: "no due date given" and "remove the due date" are both expressible.

Safety rails

The server refuses rather than guesses where guessing would be silent:

  • An ambiguous uid. UIDs are per-list, so searching every list can find more than one — an interrupted move_task deliberately leaves two copies. Rather than let list ordering decide which task an update or delete lands on, tools report the matching lists and ask you to name one.

  • Dates that do not exist. 2026-02-30, 2026-13-01 and 25:00:00 are rejected, not quietly normalised to a different date. So is a wall-clock time a zone skips for daylight saving.

  • Contradictory dates. RFC 5545 requires DUE and DTSTART to share a value type with DUE later than DTSTART, and forbids DUE alongside DURATION. Combinations that break those rules are rejected before the write, when an edit touched a date — a task another client already wrote in an invalid state stays fully editable in every other respect.

  • Timezones with nothing to qualify. dueTimezone without due would change nothing while still bumping the task's revision, so it is an error rather than a silent no-op.

  • Redirects off the configured origin. Node's fetch follows redirects anywhere by default, which would let a compromised endpoint point this process at localhost or a metadata service and return the response through tool output. Only same-origin redirects are followed, plus an http→https upgrade on the same host.

Concurrency

get_task returns the task's etag. Passing it back to update_task, complete_task or delete_task makes the write conditional — if the task changed on the server in the meantime, the write is refused. Unlike the Notes API, a CalDAV 412 carries no body, so the error says how to get the current state rather than pretending to carry it.

Dates

iCalendar distinguishes a whole day from an instant, and both from a floating local time. Flattening them into one UTC timestamp is the standard way to move an all-day task onto the wrong day, so the distinction is preserved in both directions:

You pass

Stored as

"2026-03-01"

a whole day (VALUE=DATE)

"2026-03-01T14:30:00Z"

a UTC instant

"2026-03-01T14:30:00" + dueTimezone: "Europe/London"

the equivalent UTC instant

"2026-03-01T14:30:00" alone

a floating time

A zoned time is converted to UTC rather than written with a TZID, because a TZID is only valid alongside a matching VTIMEZONE and ical.js cannot generate one for an arbitrary zone. The UTC instant is exact and every client renders it in the reader's own zone.

Subtasks

Subtasks are RELATED-TO;RELTYPE=PARENT links. Set parentUid on create or update; list_tasks with nest: true returns the tree. Two constraints come from the format rather than from this server:

  • A parent must be in the same list as its subtask — RELATED-TO names a UID with no collection qualifier, so the link does not resolve across lists. move_task moves one task, so move a parent and its subtasks together if you want the hierarchy to survive.

  • delete_task does not cascade. Subtasks are left in place and reported as orphanedSubtasks, so nothing is destroyed that was not named.

Re-parenting is checked for cycles, and a task cannot be its own parent.

Repeating tasks

complete_task refuses a task that repeats — by RRULE, by explicit RDATEs, or both. Completing a repeating task has to advance it to its next occurrence; writing STATUS:COMPLETED onto the master component instead ends the series permanently, and the occurrences still to come cannot be recovered from it. Recurrence is reported on every task as recurrenceRule and preserved through every write — it is just not editable here. Complete or edit repeating tasks in the Tasks UI.

Install

There is no published npm package. Install the release tarball, which puts the tasks-mcp command on your PATH:

# Download tasks-mcp-<version>.tgz from the latest release, then:
npm install -g ./tasks-mcp-<version>.tgz

The asset is attached to each release.

To build it yourself instead, either pack the same tarball:

corepack pnpm install
corepack pnpm pack:tarball
npm install -g ./tasks-mcp-<version>.tgz

or skip the global install and point the client at the built entry point:

corepack pnpm install
corepack pnpm build

Configuration

Add to your MCP client config (Claude Code shown). After a global install:

{
  "mcpServers": {
    "tasks": {
      "command": "tasks-mcp",
      "args": [],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.example.com",
        "NEXTCLOUD_USER": "your-username",
        "NEXTCLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Or, running from the build directory, with an absolute path to dist/index.js:

{
  "mcpServers": {
    "tasks": {
      "command": "node",
      "args": ["/absolute/path/to/nc_tasks-mcp/dist/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud.example.com",
        "NEXTCLOUD_USER": "your-username",
        "NEXTCLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Generate the app-password in Nextcloud under Settings > Security > Devices & sessions > "Create new app password". The MCP server only needs an app-password, never your real account password — and you can revoke it without affecting your main login.

Development

corepack pnpm install
corepack pnpm dev        # stdio MCP server, point mcp inspector at it
corepack pnpm test       # deterministic unit tests, no Nextcloud required
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm build      # tsc -> dist/

Required env vars: NEXTCLOUD_URL, NEXTCLOUD_USER, NEXTCLOUD_APP_PASSWORD.

Optional:

Variable

Default

Purpose

NEXTCLOUD_DEFAULT_TASK_LIST

unset

List used when a tool needs one and the caller omits it. Matched on uri, then display name. Unnecessary if the account has only one list.

NEXTCLOUD_TIMEOUT_MS

60000

Per-request deadline. Must be a whole number of milliseconds, at most 2147483647.

NEXTCLOUD_MAX_RESPONSE_BYTES

20971520

Largest response body buffered. A calendar-query returns every matching task's full iCalendar body in one document, so this scales with list size rather than page size.

DEBUG

unset

Log each request to stderr.

Disclosure

This project was 100% written by AI (Claude), including all source code, tests, CI configuration, and documentation.

License

MIT — see LICENSE.

Available Tools

11 tools
complete_taskA
Idempotent

Mark a task done: status COMPLETED, 100 percent, completed timestamp now. Repeating tasks are refused — completing one has to advance it to its next occurrence, and closing it here would end the series.

Inputs: uid (required), etag, list.

create_taskA

Create a task. The list may be omitted when the account has one task list or NEXTCLOUD_DEFAULT_TASK_LIST is set. Returns the task as stored, including its new uid.

Inputs: summary (required), due, list, start, +12 more.

delete_taskA
DestructiveIdempotent

Delete a task permanently. Subtasks are not deleted — they are left in place and reported as orphaned, so nothing is destroyed that was not named.

Inputs: uid (required), etag, list.

get_taskA
Read-onlyIdempotent

Read one task by uid, including its etag. Naming the list makes this one request instead of one per list.

Inputs: uid (required), list.

list_tagsA
Read-onlyIdempotent

List the tags in use with a count of the tasks carrying each, completed ones included. Useful for finding the exact spelling of a tag before filtering list_tasks by it.

Inputs: list.

list_task_listsA
Read-onlyIdempotent

List the task lists in this account. Use the returned "uri" wherever a tool takes a list — it is stable, whereas the display name changes on rename and need not be unique.

Inputs: no named parameters.

list_tasksA
Read-onlyIdempotent

List tasks, earliest deadline first. Searches every task list unless one is named. Completed and cancelled tasks are excluded unless includeCompleted is true. Results are sorted by due date, then priority, then title.

Inputs: list, nest, tags, limit, +7 more.

move_taskA
Idempotent

Move a task to another task list, keeping its uid and every property. Subtasks are not moved with it, and a parent link only resolves within one list, so move a parent and its subtasks together if you want the hierarchy to survive.

Inputs: uid (required), toList (required), list.

pingA
Read-onlyIdempotent

Verify connectivity and credentials against Nextcloud CalDAV. Returns the configured server and user, the discovered calendar home, and the task lists found there.

Inputs: no named parameters.

uncomplete_taskA
Idempotent

Reopen a completed task: status NEEDS-ACTION, completion timestamp removed.

Inputs: uid (required), etag, list.

update_taskA
Idempotent

Change fields on an existing task. Only the fields given are touched; everything else on the task — including recurrence, reminders and properties written by other CalDAV clients — is preserved. Pass null to clear a field. Pass an etag to make the write conditional on nobody else having changed the task first.

Inputs: uid (required), due, etag, list, +14 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct action on tasks or task lists: ping for connectivity, CRUD operations, state changes (complete/uncomplete), moving, and tag listing. No two tools overlap in purpose, and descriptions clarify any potential confusion (e.g., complete_task vs. update_task).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: list_task_lists, create_task, delete_task, etc. The only deviation is 'ping', which is a conventional standalone verb but fits the pattern of a simple connectivity check. No mixed conventions or vague verbs.

    Tool Count5/5

    With 11 tools, the server is well-scoped for task management: it covers connectivity, list retrieval, task CRUD, lifecycle transitions, moving, and tag utilities. The count is within the ideal range and each tool earns its place without redundancy.

    Completeness5/5

    The tool surface provides comprehensive coverage of task management: create, read, update, delete, complete/uncomplete, move, and list/filter. The inclusion of tags and the detailed handling of recurrence and subtasks in descriptions address edge cases, leaving no obvious dead ends for agents.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      This MCP server connects AI assistants to CalDAV servers so they can list calendars, manage events, and handle tasks (VTODOs) directly. It enables creating, updating, completing, and deleting events and todos, with support for date-range queries, recurrence rules, all-day events, and status-based task filtering.
      897 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to connect to CalDAV servers and manage calendars, events, and tasks through MCP tools, including listing, creating, updating, completing, and deleting items.
      897 npm
      MIT