tan yong sheng triliumnext mcp

⚠️ 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

• perfectra1n/triliumnext-mcp
• perfectra1n/triliumnext-cli

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 to search_notes, get_note, resolve_note_id, and read_attributes, and WRITE grants access to create_note, update_note, delete_note, and manage_attributes)
• VERBOSE (optional, default='false', which if true will print verbose debugging logs)

Below are the installation guide for this MCP on different MCP clients, such as Claude Desktop, Claude Code, Cursor, Cline, etc.

{
  "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-mcp

{
  "env": {
    "MCP_TIMEOUT": "60000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

npx triliumnext-mcp

docker pull ghcr.io/tan-yong-sheng/triliumnext-mcp:latest

{
  "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"
      }
    }
  }
}

The server provides the following tools for note management:

• 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.

• 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 a mode ('overwrite' or 'append') to specify the update type and an expectedHash to prevent conflicts.
• move_note - Move a note to a new parent folder. Use branchId only 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 use occurrence and optional context to target repeated text.
• delete_note - Permanently delete a note (⚠️ cannot be undone).

• 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.

• "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"

• "Add today's update to my work log" (uses update_note with mode: 'append')
• "Replace this draft with the final version" (uses update_note with mode: 'overwrite')
• "Create a new note called 'Weekly Review' in my journal folder"

📖 More Examples: See User Query Examples for comprehensive usage scenarios.

• 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

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 watch

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.