Skip to main content
Glama

notes-mcp

A Model Context Protocol server for Nextcloud Notes — exposes notes, categories and app settings to Claude and any MCP-compatible client.

How it works

The server speaks one API: the Notes REST API at /index.php/apps/notes/api/v1.

Unlike most Nextcloud apps this is not an OCS endpoint — it returns bare JSON with conventional HTTP status codes, and note bodies travel inline in the content field. There is no WebDAV leg, so no path arithmetic and no file locking to contend with.

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

Related MCP server: notes-box

Tools exposed (12)

  • Notes: list_notes, get_note, create_note, update_note, append_to_note, delete_note

  • Categories: list_categories, set_note_category, rename_category

  • Settings: get_settings, update_settings

  • Other: ping

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

Concurrency

get_note returns the note's etag. Passing it back to update_note makes the write conditional: if the note changed on the server in the meantime, the write is refused and the error carries the server's current copy of the note, so a caller can merge and retry without a second round-trip. append_to_note does this internally.

Categories

A category is a folder under the notes folder, named by each note's category field and nested with /. Two consequences shape the tools:

  • The server's category filter is an exact string comparison, so list_notes takes recursive to include subcategories such as work/clients under work.

  • There is no category endpoint and no server-side rename. list_categories derives the list from the notes themselves, so a category holding no notes does not appear. rename_category rewrites every affected note individually and reports the per-note outcome, because the operation is not atomic.

Install

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

# Download notes-mcp-<version>.tgz from the latest release, then:
npm install -g ./notes-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 ./notes-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": {
    "notes": {
      "command": "notes-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": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/notes-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_TIMEOUT_MS

60000

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

NEXTCLOUD_MAX_RESPONSE_BYTES

10485760

Largest response body buffered. Raise it for very large notes.

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

12 tools
append_to_noteA

Append text to the end of a note without resending its whole body. Reads the note and writes it back conditionally, so a concurrent edit is reported rather than overwritten.

Inputs: id (required), text (required), separator.

create_noteA

Create a note. The category is a "/"-delimited folder path and is created automatically if missing. The server sanitises the title and category, so use the values in the response rather than the ones supplied.

Inputs: title, content, category, favorite.

delete_noteB
DestructiveIdempotent

Delete a note. The note file goes to the Nextcloud trash, so it is recoverable from the Files app until the trash is emptied, but this server cannot restore it.

Inputs: id (required).

get_noteA
Read-onlyIdempotent

Fetch one note including its content and etag. Pass the etag to update_note to make the write conditional on nothing else having changed the note first.

Inputs: id (required), exclude.

get_settingsA
Read-onlyIdempotent

Read the Notes app settings: notes folder, file suffix, editor mode, and whether hidden files count as notes.

Inputs: no named parameters.

list_categoriesA
Read-onlyIdempotent

List every category that contains at least one note, with direct and recursive note counts. Categories are derived from the notes themselves because the Notes API has no endpoint for them, so a category holding no notes will not appear here even though the Notes app shows it.

Inputs: no named parameters.

list_notesA
Read-onlyIdempotent

List notes, optionally filtered by category. The server matches categories exactly, so pass recursive=true to include subcategories such as "work/clients" under "work". Use exclude=["content"] to keep the response small when only metadata is needed.

Inputs: exclude, category, chunkSize, recursive, +2 more.

pingA
Read-onlyIdempotent

Verify connectivity and credentials against the Nextcloud Notes API. Returns the configured server, user and the notes folder settings.

Inputs: no named parameters.

rename_categoryA
Destructive

Rename a category by moving every note in it. The Notes API has no category rename, so this rewrites each note individually and is not atomic: a partial failure leaves some notes moved. The per-note outcome is reported. Pass recursive=true to re-parent nested subcategories too.

Inputs: to (required), from (required), recursive.

set_note_categoryA
DestructiveIdempotent

Move a note to a category, creating the category if it does not exist. Pass "" to make the note uncategorized. Any attachments move with the note.

Inputs: id (required), category (required), etag.

update_noteA
DestructiveIdempotent

Update a note. Only the supplied fields change. Passing content replaces the whole body — use append_to_note to add to it. Pass the etag from get_note to refuse the write if someone else changed the note first.

Inputs: id (required), etag, title, content, +2 more.

update_settingsA
DestructiveIdempotent

Change the Notes app settings. Set fileSuffix to the extension itself, including the dot — ".md", ".org", or any custom extension; the server stores a non-standard one as the custom suffix. Changing notesPath re-points the app at a different folder: notes in the old folder stop appearing in Notes until it is pointed back.

Inputs: noteMode, notesPath, fileSuffix, showHidden, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: ping/get_settings read connectivity and settings; list_notes/get_note retrieve; create/update/append/delete modify; category tools manage categorization. The append vs update distinction is explicitly clarified in descriptions, and set_note_category vs rename_category are well-separated.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun snake_case pattern (get_note, create_note, update_note, delete_note, list_notes, etc.). Minor deviations like 'ping' and 'get_settings' break the resource_verb pattern slightly but remain readable and predictable.

    Tool Count5/5

    12 tools is well-scoped for a notes server covering CRUD, settings, and category management. Each tool earns its place with no redundancy; the count sits comfortably in the ideal 3-15 range.

    Completeness4/5

    Full note lifecycle (create/read/update/append/delete) and category management are covered, plus settings and connectivity checks. Minor gap: no restore_note despite delete going to trash, and list_categories excludes empty categories, but these are documented limitations rather than dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers