TriliumNext Notes' MCP Server
The TriliumNext Notes' MCP Server allows you to manage notes through the Model Context Protocol with these core functions:
Search Notes: Query notes with options for fast search and including archived items
Get Note: Retrieve a specific note by ID, with option to include/exclude content
Create Note: Add new notes with specified parent, title, type, and content; supports various formats (text, code, image) with optional MIME type
Update Note: Modify existing notes by changing title and content
Delete Note: Permanently remove notes by ID
Provides tools for interacting with a Trilium Notes instance, enabling note management operations including creating, searching, retrieving, updating, and deleting notes of various types (text, code, file, image, search, book, relationMap, render).
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., "@TriliumNext Notes' MCP Server search for my meeting notes from last week"
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.
TriliumNext Notes' MCP Server
⚠️ DISCLAIMER: This is a prototype for https://github.com/TriliumNext/Notes/issues/705. Suggested only for developer use. Please backup your Trilium notes before using this tool. ⚠️
A model context protocol server for TriliumNext Notes. This server provides tools to interact with your Trilium Notes instance through MCP. You can use this MCP with triliumnext-skills.
Also, if you would like to back up your trilium instances to multiple cloud storage providers such as cloudflare R2, AWS S3 and google drive simultaneously, please visit: https://github.com/tan-yong-sheng/trilium-backup
Alternatives to suggest:
Related MCP server: MCP TriliumNext
Quick Start
Make sure to set up your environment variables first:
TRILIUM_API_URL(default: http://localhost:8080/etapi)TRILIUM_API_TOKEN(required, get this from your Trilium Notes settings)PERMISSIONS(optional, default='READ;WRITE', where READ grants access tosearch_notes,get_note,resolve_note_id, andread_attributes, and WRITE grants access tocreate_note,update_note,delete_note, andmanage_attributes)VERBOSE(optional, default='false', which if true will print verbose debugging logs)
Installation
Below are the installation guide for this MCP on different MCP clients, such as Claude Desktop, Claude Code, Cursor, Cline, etc.
Add to your Claude Desktop configuration:
{
"mcpServers": {
"triliumnext-mcp": {
"command": "npx",
"args": ["triliumnext-mcp"],
"env": {
"TRILIUM_API_URL": "http://localhost:8080/etapi",
"TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
"PERMISSIONS": "READ;WRITE"
}
}
}
}claude mcp add triliumnext-mcp \
-e TRILIUM_API_URL=http://localhost:8080/etapi \
-e TRILIUM_API_TOKEN=<YOUR_TRILIUM_API_TOKEN> \
-e PERMISSIONS='READ;WRITE' \
-- npx triliumnext-mcpNote: Increase the MCP startup timeout to 1 minutes and MCP tool execution timeout to about 5 minutes by updating ~\.claude\settings.json as follows:
{
"env": {
"MCP_TIMEOUT": "60000",
"MCP_TOOL_TIMEOUT": "300000"
}
}Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server
Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.
{
"mcpServers": {
"triliumnext-mcp": {
"command": "npx",
"args": ["triliumnext-mcp"],
"env": {
"TRILIUM_API_URL": "http://localhost:8080/etapi",
"TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
"PERMISSIONS": "READ;WRITE"
}
}
}
}Cline uses a JSON configuration file to manage MCP servers. To integrate the provided MCP server configuration:
Open Cline and click on the MCP Servers icon in the top navigation bar.
Select the Installed tab, then click Advanced MCP Settings.
In the cline_mcp_settings.json file, add the following configuration:
(i) Using Google AI Studio Provider
{
"mcpServers": {
"timeout": 300,
"type": "stdio",
"triliumnext-mcp": {
"command": "npx",
"args": ["triliumnext-mcp"],
"env": {
"TRILIUM_API_URL": "http://localhost:8080/etapi",
"TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
"PERMISSIONS": "READ;WRITE"
}
}
}
}The server uses stdio transport and follows the standard MCP protocol. It can be integrated with any MCP-compatible client by running:
npx triliumnext-mcpUsing Pre-built Image from GitHub Container Registry
Pull and run the latest image:
docker pull ghcr.io/tan-yong-sheng/triliumnext-mcp:latestThen, put this configuration for your your mcp: (Note: remember to change your TRILIUM_API_URL and TRILIUM_API_TOKEN here)
{
"mcpServers": {
"triliumnext-mcp-docker": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"TRILIUM_API_URL",
"-e",
"TRILIUM_API_TOKEN",
"-e",
"PERMISSIONS",
"-e",
"VERBOSE",
"ghcr.io/tan-yong-sheng/triliumnext-mcp:latest"
],
"env": {
"TRILIUM_API_URL": "https://trilium:8080/etapi",
"TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
"PERMISSIONS": "READ;WRITE",
"VERBOSE": "false"
}
}
}
}Available Tools
The server provides the following tools for note management:
Search & Discovery Tools
search_notes- Unified search with comprehensive filtering capabilities including keyword search, date ranges, field-specific searches, attribute searches, note properties, template-based searches, note type filtering, MIME type filtering, and hierarchy navigation.resolve_note_id- Find a note's ID by its title. Essential for getting a note's ID to use with other tools.list_children_notes- List the direct child notes of a parent note using a deterministic search query. Returns child summaries sorted by creation date and title.
Note Management Tools
get_note- Retrieve a note and its content by ID. Can also be used with regex to extract specific patterns from the content.create_note- Create a new note. Supports 10 note types and allows creating attributes (labels and relations) in the same step.update_note- Updates a note's title or content. Requires amode('overwrite'or'append') to specify the update type and anexpectedHashto prevent conflicts.move_note- Move a note to a new parent folder. UsebranchIdonly when the note has multiple parent branches.patch_note- Apply targeted batched edits using mode-based patches (css,xpath,line,fragment,literal,regex) with atomic validation. Literal patches can useoccurrenceand optionalcontextto target repeated text.delete_note- Permanently delete a note (⚠️ cannot be undone).
Attribute Management Tools
read_attributes- Read all attributes (labels and relations) for a given note.manage_attributes- Create, update, or delete attributes on a note. Supports batch creation.
📖 Detailed Usage: See Note Management Guide for revision control strategy and best practices.
Example Queries
Search & Discovery
"Find my most recent 10 notes about 'n8n' since the beginning of 2024"
"Show me notes I've edited in the last 7 days"
"List all notes under 'n8n Template' folder, including subfolders"
"List the direct child notes of this folder"
Content Management
"Add today's update to my work log" (uses
update_notewithmode: 'append')"Replace this draft with the final version" (uses
update_notewithmode: 'overwrite')"Create a new note called 'Weekly Review' in my journal folder"
📖 More Examples: See User Query Examples for comprehensive usage scenarios.
Documentation
Docker Deployment Guide - Complete guide for running with Docker
Note Management Guide - Safe content editing with revision control
Patch Note Guide - Targeted batched note editing
Move Note Guide - Moving notes between parents
List Children Notes Guide - Direct child listing
User Query Examples - Natural language query examples
Search Query Examples - Advanced search syntax and filters
Development
If you want to contribute or modify the server:
# Clone the repository
git clone https://github.com/tan-yong-sheng/triliumnext-mcp.git
# Install dependencies
npm install
# Build the server
npm run build
# For development with auto-rebuild
npm run watchContributing
Contributions are welcome! If you are looking to improve the server, please familiarize yourself with the official Trilium Search DSL documentation and our internal Search Query Examples to understand how search queries are constructed.
Please feel free to open an issue or submit a pull request.
Available Tools
9 toolscreate_noteA
Create a new note in TriliumNext with duplicate title detection. When a note with the same title already exists in the same directory, you'll be presented with choices: skip creation, create anyway (with forceCreate: true), or update the existing note. ONLY use this tool when the user explicitly requests note creation (e.g., 'create a note', 'make a new note'). DO NOT use this tool proactively or when the user is only asking questions about their notes. TIP: For code notes, content is plain text (no HTML processing).
Inputs: parentNoteId (required), title (required), type (required), content, +4 more.
delete_noteA
Delete a note permanently. ONLY use this tool when the user explicitly requests note deletion (e.g., 'delete the note', 'remove this note', 'delete this permanently'). TRY NOT to use this tool proactively or for automated cleanup. CAUTION: This action cannot be undone and will permanently remove the note and all its content.
Inputs: noteId (required).
get_noteA
Get a note and its content by ID. Perfect for when someone wants to see what's in a note, extract specific information, or prepare for search and replace operations. Getting the full content lets you see the context and create better regex patterns for extraction or replacement. ⚠️ SMART CONTENT INCLUSION: For file/image notes, binary content is automatically excluded by default for performance. Use includeBinaryContent: true to explicitly retrieve binary data when needed.
Inputs: noteId (required), includeContent, includeBinaryContent, searchPattern, +2 more.
manage_attributesA
Manage note attributes with write operations (create, update, delete). Create labels (#tags), template relations (~template), update existing attributes, and organize notes with metadata. IMPORTANT: This tool only provides write access - use read_attributes to view existing attributes. Relations require values pointing to existing notes (e.g., template relations use 'Board', 'Calendar'; author relations use target note titles or IDs). UPDATE LIMITATIONS: For labels, only value and position can be updated. For relations, only position can be updated. The isInheritable property cannot be changed via update - delete and recreate to modify inheritability. Supports single operations and efficient batch creation for better performance.
Inputs: noteId (required), operation (required), attributes.
read_attributesA
Read all attributes (labels and relations) for a note. View existing labels (#tags), template relations (~template), and note metadata. This tool provides read-only access to inspect current attributes assigned to any note. Returns structured data with labels, relations, and summary information.
Inputs: noteId (required).
resolve_note_idA
Resolves a note/folder name to its actual note ID for use with other tools. You MUST call this function when users provide note names instead of note IDs (e.g., 'wqd7006', 'My Project') UNLESS the user explicitly provides a note ID. Simple title-based search with user choice when multiple matches found.
Inputs: noteName (required), exactMatch, maxResults, autoSelect.
search_and_replace_noteA
Search and replace content within a single note. When someone wants to replace text in a note, first call get_note to get the current content and hash, then use this function to make the changes. This ensures you're working with the latest version of their note.
Inputs: noteId (required), searchPattern (required), replacePattern (required), expectedHash (required), +3 more.
search_notesA
Unified search with comprehensive filtering capabilities including keyword search, date ranges, field-specific searches, attribute searches, note properties, template-based searches, note type filtering, MIME type filtering, and hierarchy navigation through unified searchCriteria structure. For simple keyword searches, use the 'text' parameter. For complex boolean logic like 'docker OR kubernetes', use searchCriteria with proper OR logic. For template search: use relation type with 'template.title' property and built-in template values like 'Calendar', 'Board', 'Text Snippet', 'Grid View', 'List View', 'Table', 'Geo Map'. For note type search: use noteProperty type with 'type' property and values from the 9 supported ETAPI types: 'text', 'code', 'render', 'search', 'relationMap', 'book', 'noteMap', 'mermaid', 'webView'. For MIME type search: use noteProperty type with 'mime' property and MIME values like 'text/javascript', 'text/x-python', 'text/vnd.mermaid', 'application/json'. Use hierarchy properties like 'parents.noteId', 'children.noteId', or 'ancestors.noteId' for navigation.
Inputs: text, searchCriteria, limit.
update_noteA
Update note with support for title-only updates, content overwrite, content append, or file replacement. ⚠️ REQUIRED: ALWAYS call get_note first to obtain current hash. ⚠️ SIMPLER RULES: Note type and MIME type are IMMUTABLE - cannot be changed after creation. MODE SELECTION: Use 'append' when user wants to add/insert content (e.g., 'append to note', 'add to the end', 'insert content', 'add more content', 'continue writing', 'add to bottom'). Use 'overwrite' when replacing entire content (e.g., 'replace content', 'overwrite note', 'update the whole note', 'completely replace'). TITLE-ONLY: Efficient title changes without content modification. FILE UPDATES: Replace file content only with SAME file type (image→image, file→file). To change file types, create a new note instead. PREVENTS: Type mismatches, file type conflicts, and overwriting changes made by other users. ONLY use when user explicitly requests note update. WORKFLOW: get_note → review content → update_note with returned hash
Inputs: noteId (required), expectedHash (required), title, content, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose with no ambiguity. For example, create_note, delete_note, get_note, update_note cover the CRUD lifecycle distinctly, while manage_attributes and read_attributes separate write and read operations cleanly. Tools like resolve_note_id and search_notes serve unique auxiliary functions without overlap.
All tool names follow a consistent verb_noun pattern with snake_case throughout, such as create_note, delete_note, get_note, update_note, manage_attributes, read_attributes, resolve_note_id, search_and_replace_note, and search_notes. This uniformity makes the set predictable and easy to understand.
With 9 tools, the count is well-scoped for a notes management server, covering core operations like CRUD, attribute handling, search, and ID resolution. Each tool earns its place without redundancy, providing a comprehensive yet manageable interface for the domain.
The tool set offers complete coverage for note management, including full CRUD (create_note, get_note, update_note, delete_note), attribute management (manage_attributes, read_attributes), search capabilities (search_notes, search_and_replace_note), and auxiliary functions (resolve_note_id). There are no obvious gaps, enabling agents to handle all typical workflows without dead ends.
Maintenance
Related MCP Connectors
Model Context Protocol server for todo.vu task management and time tracking.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseCqualityDmaintenanceA Model Context Protocol server that implements a simple notes system, allowing users to create, list, and summarize text notes.3-
- AlicenseBqualityDmaintenanceA Model Context Protocol server enabling AI assistants to interact with TriliumNext notes, providing tools for creating, searching, reading, and updating notes in your knowledge base.42MIT
- AlicenseBqualityDmaintenanceA simple server for saving, listing, and searching notes persisted to a local JSON file. It enables users to manage their personal notes using natural language via the Model Context Protocol.3ISC
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for managing text notes, with resources (note:// URIs), tools (create_note), and prompts (summarize_notes).-