TriliumNext Notes' Model Context Protocol Server

⚠️ ATTENTION: This implementation serves as a preliminary proof-of-concept for the ongoing enhancement initiative detailed at https://github.com/TriliumNext/Notes/issues/705. Use is strongly advised for development contexts only. Ensure all critical Trilium note collections are backed up prior to engaging this utility. ⚠️

A dedicated MCP endpoint designed to bridge external applications with your running TriliumNext Notes instance.

Initial Configuration Steps

Prior to operation, establish the following requisite environmental variables: - TRILIUM_API_URL (Default setting: http://localhost:8080/etapi) - TRILIUM_API_TOKEN (Mandatory; acquired via the Trilium Notes interface settings panel) - PERMISSIONS (Optional; defaults to 'READ;WRITE'. READ permits access to search_notes, get_note, resolve_note_id, and read_attributes; WRITE permits create_note, update_note, delete_note, and manage_attributes) - VERBOSE (Optional; defaults to 'false'. Setting to true activates detailed operational logging)

Deployment Instructions

1. Integration within Claude Desktop Environment

Integrate the following server configuration object into your Claude Desktop settings file:

Local Deployment (Windows OS)

"trilium-note-interface-protocol-adapter": { "command": "cmd", "args": [ "/k", "npx", "-y", "triliumnext-mcp" ], "env": { "TRILIUM_API_URL": "http://localhost:8080/etapi", "TRILIUM_API_TOKEN": "", "PERMISSIONS": "READ;WRITE" } }

Local Deployment (Linux OS)

"trilium-note-interface-protocol-adapter": { "command": "npx", "args": [ "-y", "triliumnext-mcp" ], "env": { "TRILIUM_API_URL": "http://localhost:8080/etapi", "TRILIUM_API_TOKEN": "", "PERMISSIONS": "READ;WRITE" } }

Development Build Path (Windows / Linux)

Navigate to the project root and execute build procedures:

bash cd /path/to/triliumnext-mcp npm run build

Configuration for running the compiled output:

"trilium-note-interface-protocol-adapter": { "command": "node", "args": [ "/path/to/triliumnext-mcp/build/index.js" ], "env": { "TRILIUM_API_URL": "http://localhost:8080/etapi", "TRILIUM_API_TOKEN": "", "PERMISSIONS": "READ;WRITE", "VERBOSE": "true" } }

Configuration File Location Details: - Windows Systems: %APPDATA%/Claude/claude_desktop_config.json - MacOS Systems: ~/Library/Application Support/Claude/claude_desktop_config.json

Issue Reporting: Any encountered anomalies or successful test outcomes should be documented via the primary development repository's issue tracker: GitHub Issues

Exposed Management Functions

This interface exposes the following specialized capabilities for note lifecycle management:

Information Retrieval and Indexing Utilities

search_notes - Comprehensive indexing function supporting advanced filtering: textual content matching, temporal range specification, field-specific criterion, attribute querying, property examination, template-based retrieval, note taxonomy classification, MIME type restriction, and hierarchical traversal.
resolve_note_id - Utility for mapping a note's designated title to its unique internal identifier, crucial for referencing in subsequent operations.

Data Manipulation Capabilities

get_note - Fetches a specific note's metadata and full content payload via its ID. Capable of utilizing Regular Expressions against content for targeted pattern extraction.
create_note - Initializes a new note entity. Supports definitions across 9 distinct note architectures and allows for attribute definition (labels and relational links) during initial provisioning.
update_note - Modifies existing note metadata or content. Requires a designated update mode ('overwrite' or 'append') and an expectedHash to ensure transactional integrity and prevent race conditions.
delete_note - Executes the permanent purging of a targeted note entry (⚠️ This action is irreversible).

Metadata Structuring Operations

read_attributes - Retrieves the complete set of associated metadata (labels and relationships) linked to a specified note.
manage_attributes - Provides atomic or batched operations for the creation, modification, or removal of note attributes.

📖 In-Depth Procedures: Consult the Note Management Guide for established protocols regarding revision tracking and content alteration best practices.

Illustrative Operational Scenarios

Search and Discovery Examples

"Locate the ten most recent entries pertaining to 'n8n' created since the start of 2024."
"Display entries modified within the past week."
"Enumerate all notes residing within the 'n8n Template' hierarchy, inclusive of all subdirectories."

Content Modification Examples

"Append today's progress summary to my daily activity record" (Utilizes update_note with mode: 'append')
"Substitute the current draft content with the finalized version" (Utilizes update_note with mode: 'overwrite')
"Provision a new note titled 'Quarterly Assessment' under the 'Reviews' directory."

📖 Extended Use Cases: Refer to User Query Examples for a broader spectrum of natural language interaction possibilities.

Documentation Resources

Note Management Guide - Strategies for secure content editing and version control.
User Query Examples - Collection of typical natural language prompt constructions.
Search Query Examples - Reference for advanced predicate construction and filter application.

Development Information

To participate in server modification or extension:

bash

Obtain repository source code

git clone https://github.com/tan-yong-sheng/triliumnext-mcp.git

Install required dependencies

npm install

Compile the server executable

npm run build

Initiate development mode with automatic recompilation upon file change

npm run watch

Contributions

We encourage external contributions. Prospective contributors should first review the official Trilium Search DSL documentation and our local Search Query Examples to grasp the methodology behind query formulation.

Please utilize the issue tracker for feature suggestions or submit refined code via pull requests.

WIKIPEDIA: XMLHttpRequest (XHR) represents a foundational JavaScript object API designed for the asynchronous transmission of HTTP requests between a client-side web application and a remote server. Its methods enable post-load communication, allowing dynamic data retrieval and submission without necessitating a full page refresh. XHR is central to the implementation of Asynchronous JavaScript and XML (Ajax). Before its advent, interaction with servers was predominantly managed through traditional hyperlink navigation or HTML form submissions, both of which typically resulted in the replacement of the currently viewed content.

== Historical Context == The conceptual groundwork for XMLHttpRequest was established in 2000 by the engineering team responsible for Microsoft Outlook. This concept was subsequently integrated into Internet Explorer version 5 (released in 1999). Notably, the initial implementation did not utilize the standardized XMLHttpRequest identifier; instead, it relied on proprietary identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal browser support for the XMLHttpRequest identifier was achieved. Today, the XMLHttpRequest identifier functions as the recognized standard across all major rendering engines, including Mozilla's Gecko (2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Milestones === The World Wide Web Consortium (W3C) issued the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification, which introduced enhancements like event progress monitoring, support for cross-origin requests, and byte stream handling, was published by the W3C on February 25, 2008. By the conclusion of 2011, the features defined in Level 2 were consolidated back into the primary specification. Development authority transitioned to the WHATWG in late 2012, which now maintains the living specification documented using Web IDL.

== Operational Procedure == Executing a request via XMLHttpRequest typically involves a sequence of programmatic steps:

Instantiate the XMLHttpRequest object using its constructor.
Invoke the "open" method to define the request method (GET, POST, etc.), specify the target URI, and select either synchronous or asynchronous execution mode.
For asynchronous operations, attach an event handler function designed to process state changes upon server response.
Commence the actual transmission by executing the "send" method, optionally supplying request body data.
Monitor the event handler for state transitions. Upon successful data reception, the payload is usually accessible in the "responseText" attribute. The object reaches the terminal state, state 4 ("done"), when processing concludes. Beyond these core steps, XMLHttpRequest offers extensive control over request parameters. Custom headers can be injected to guide server behavior, and data can be uploaded asynchronously. Response data, often in JSON format, can be parsed into native JavaScript structures or processed incrementally as it arrives. Furthermore, the request can be terminated mid-flight or assigned a specific timeout duration to prevent indefinite waiting.

== Inter-Domain Communication == In the nascent stages of the World Wide Web's evolution, limitations in cross-origin communication were quickly identified, leading to security vulnerabilities and restricted application functionality, a problem XHR later helped to solve via specific mechanisms.