notes-mcp
Provides tools for interacting with the Nextcloud Notes REST API, enabling management of notes, categories, and app settings in a Nextcloud Notes instance. Capabilities include listing, retrieving, creating, updating, appending to, and deleting notes, as well as listing and renaming categories and reading or updating settings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notes-mcp append 'pick up dry cleaning' to my todo note"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_noteCategories:
list_categories,set_note_category,rename_categorySettings:
get_settings,update_settingsOther:
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
categoryfilter is an exact string comparison, solist_notestakesrecursiveto include subcategories such aswork/clientsunderwork.There is no category endpoint and no server-side rename.
list_categoriesderives the list from the notes themselves, so a category holding no notes does not appear.rename_categoryrewrites 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>.tgzThe 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>.tgzor skip the global install and point the client at the built entry point:
corepack pnpm install
corepack pnpm buildConfiguration
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 |
|
| Per-request deadline. Must be a whole number of milliseconds, at most 2147483647. |
|
| Largest response body buffered. Raise it for very large notes. |
| 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.
Related
Nextcloud Notes and its API reference
nc_collectives-mcp — the same approach for Nextcloud Collectives
Available Tools
12 toolsappend_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_noteBDestructiveIdempotent
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_noteARead-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_settingsARead-onlyIdempotent
Read the Notes app settings: notes folder, file suffix, editor mode, and whether hidden files count as notes.
Inputs: no named parameters.
list_categoriesARead-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_notesARead-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.
pingARead-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_categoryADestructive
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_categoryADestructiveIdempotent
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_noteADestructiveIdempotent
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_settingsADestructiveIdempotent
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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Read and write your Caliu notes from any MCP client: search, create, tag, remind, attach files.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables managing notes through a simple MCP server, providing tools to add, retrieve, update, delete, and list notes for use with Claude Desktop.MIT
- AlicenseNot gradedqualityCmaintenanceEnables creating, retrieving, updating, deleting, and listing notes through a simple MCP interface, with configurable note storage.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible clients to create, list, search, and delete notes, read all notes as markdown, and use prompts to summarize or clean up notes.MIT
- AlicenseNot gradedqualityCmaintenanceEnables LLM agents to read and write Nextcloud files, notes, calendars, tasks, contacts, and Talk messages through a secure authenticated MCP endpoint.MIT