Skip to main content
Glama
RadonX

MCP TriliumNext

by RadonX
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

MCP TriliumNext

A Model Context Protocol (MCP) server for TriliumNext, providing AI assistants with seamless access to your note-taking workflow.

Overview

This MCP server enables AI assistants like Claude to interact with your TriliumNext notes through a standardized protocol. It provides tools for creating, searching, reading, and updating notes, as well as accessing recent notes as a resource.

Related MCP server: TriliumNext Notes' MCP Server

Features

🛠️ Tools

  • create_note - Create new notes with title, content, and type

  • search_notes - Search notes using fulltext or structured queries

  • get_note - Retrieve complete note details and content

  • update_note - Update existing note content

📚 Resources

  • trilium://recent-notes - Access to 10 most recently modified notes

✨ Key Capabilities

  • Full CRUD operations for notes

  • Advanced search with TriliumNext query syntax

  • Structured data preservation for AI consumption

  • Comprehensive error handling and validation

  • Production-ready logging and monitoring

Installation

Prerequisites

  • Node.js 18.0.0 or higher

  • TriliumNext server running and accessible

  • ETAPI token from your TriliumNext instance

Setup

  1. Clone and install

    git clone git@github.com:RadonX/mcp-trilium.git
cd mcp-trilium
npm install

  2. Configure environment Create a .env file with your settings:

    TRILIUM_URL=http://localhost:8080
TRILIUM_AUTH_TOKEN=your_etapi_token_here
REQUEST_TIMEOUT=30000
LOG_LEVEL=info

  3. Get your ETAPI token

    • Open TriliumNext web interface

    • Go to Options → ETAPI

    • Create a new token or use existing one

    • Copy the token to your .env file

  4. Test connectivity

    npm run test-connectivity

Usage

With Claude Code

Add the MCP server directly using Claude Code:

claude mcp add trilium-mcp node /path/to/mcp-trilium/src/index.js --env TRILIUM_URL=http://localhost:8080 --env TRILIUM_AUTH_TOKEN=your_etapi_token_here --env REQUEST_TIMEOUT=30000 --env LOG_LEVEL=info

With Claude Desktop

Add to your Claude Desktop configuration (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "trilium": {
      "command": "node",
      "args": ["/path/to/mcp-trilium/src/index.js"],
      "env": {
        "TRILIUM_URL": "http://localhost:8080",
        "TRILIUM_AUTH_TOKEN": "your_token_here"
      }
    }
  }
}

With MCP Inspector

npx @modelcontextprotocol/inspector src/index.js

Standalone Usage

npm start

Examples

Creating a Note

// Ask Claude: "Create a note about TypeScript basics"
{
  "tool": "create_note",
  "arguments": {
    "title": "TypeScript Basics",
    "content": "# TypeScript Fundamentals\n\nTypeScript is a typed superset of JavaScript...",
    "type": "text",
    "parentNoteId": "root"
  }
}

Searching Notes

// Ask Claude: "Find all notes about JavaScript"
{
  "tool": "search_notes",
  "arguments": {
    "query": "javascript #programming",
    "limit": 10
  }
}

Updating Content

// Ask Claude: "Update my JavaScript notes with new ES6 features"
{
  "tool": "update_note",
  "arguments": {
    "noteId": "note123abc",
    "content": "Updated content with ES6 features..."
  }
}

Search Query Syntax

TriliumNext supports powerful search queries:

  • Fulltext: machine learning algorithms

  • Exact match: "neural networks"

  • Labels: #programming #javascript

  • Combined: "react hooks" #programming type:code

  • Date filters: dateCreated:>2024-01-01

Development

Running Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Project Structure

src/
├── index.js           # Main MCP server
├── tools/             # MCP tool implementations
│   ├── create-note.js
│   ├── search-notes.js
│   ├── get-note.js
│   └── update-note.js
├── resources/         # MCP resource implementations
│   └── recent-notes.js
└── utils/             # Shared utilities
    ├── trilium-client.js
    ├── validation.js
    └── logger.js

API Reference

TriliumNext ETAPI

This server uses TriliumNext's External API (ETAPI). Key endpoints:

  • GET /notes - Search notes

  • POST /create-note - Create note

  • GET /notes/{id} - Get note details

  • PUT /notes/{id}/content - Update note content

See docs/trilium-etapi-specification.md for complete API documentation.

Configuration

Environment Variables

  • TRILIUM_URL - TriliumNext server URL (default: http://localhost:8080)

  • TRILIUM_AUTH_TOKEN - ETAPI authentication token (required)

  • REQUEST_TIMEOUT - API request timeout in ms (default: 30000)

  • LOG_LEVEL - Logging level: error, warn, info, debug (default: info)

Note Types

Supported note types:

  • text - Rich text notes (default)

  • code - Code snippets with syntax highlighting

  • file - File attachments

  • image - Image notes

  • search - Saved searches

  • book - Book/chapter organization

  • relationMap - Visual relation maps

  • canvas - Freeform canvas notes

Troubleshooting

Common Issues

Authentication Failed

# Check your token
curl -H "Authorization: Bearer your_token" http://localhost:8080/etapi/app-info

Connection Refused

  • Verify TriliumNext is running

  • Check TRILIUM_URL in .env

  • Ensure ETAPI is enabled in TriliumNext settings

Content Stored as [Object]

  • Fixed in v0.1.0 - content now properly sent as text/plain

  • Update to latest version if experiencing this issue

Debug Mode

LOG_LEVEL=debug npm start

Contributing

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature-name

  3. Make your changes with tests

  4. Run the test suite: npm test

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

Future Enhancements

The following features may be added in future versions:

🚀 Planned Features

  • Enhanced note types support - Full support for all TriliumNext note types (relationMap, canvas, etc.)

  • Advanced search features - Attribute-based queries, date range filters, and complex search operators

  • Performance optimizations - Caching, batch operations, and streaming for large note collections

  • Note relationship management - Tools for managing note relationships and hierarchies

  • Bulk operations - Create, update, or delete multiple notes in a single operation

  • Attachment handling - Support for file uploads and downloads

  • Real-time updates - WebSocket integration for live note synchronization

💡 Potential Integrations

  • Export capabilities - Export notes to various formats (Markdown, PDF, etc.)

  • Template system - Predefined note templates for common use cases

  • Backup and restore - Automated backup functionality through MCP

  • Analytics and insights - Note usage statistics and content analysis

Changelog

v0.1.0

  • Initial release with full CRUD operations

  • MCP resource for recent notes

  • Comprehensive test coverage (94 tests)

  • Production-ready error handling and validation

Made with ❤️ for the TriliumNext and MCP communities

Available Tools

4 tools
create_noteC

Create a new note in TriliumNext

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesThe title of the note (max 200 characters)
contentYesThe content of the note (max 1MB)
typeNoThe type of note to createtext
parentNoteIdNoID of the parent note (defaults to "root" if not provided)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permissions needed, whether it's idempotent, error handling, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that states the core purpose without any wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after creation (e.g., returns note ID), error conditions, or behavioral nuances. Given the complexity of a mutation operation, more context is needed for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, resulting in the baseline score of 3 where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Create') and resource ('a new note in TriliumNext'), making the purpose immediately understandable. However, it doesn't differentiate this from sibling tools like 'update_note' or explain when to create versus update, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'update_note' or 'search_notes'. There's no mention of prerequisites, context, or exclusions, leaving the agent with minimal usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_noteC

Get details of a specific note

ParametersJSON Schema
NameRequiredDescriptionDefault
noteIdYesThe ID of the note to retrieve

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves note details, implying a read-only operation, but doesn't cover aspects like error handling (e.g., what happens if the noteId is invalid), authentication needs, rate limits, or return format, which are critical for an agent to use it correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, straightforward sentence: 'Get details of a specific note'. It's appropriately sized and front-loaded, with no wasted words, making it efficient. However, it could be slightly more structured by including key details upfront, but it's concise enough to earn a high score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a read operation with one parameter) and the absence of annotations and output schema, the description is incomplete. It doesn't explain what 'details' are returned, error scenarios, or how it differs from siblings, leaving gaps that could hinder an agent's ability to use the tool effectively without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with 'noteId' clearly documented as 'The ID of the note to retrieve'. The description adds no additional meaning beyond this, as it doesn't explain parameter usage or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get details of a specific note' clearly states the verb 'Get' and resource 'note', making the purpose understandable. However, it lacks specificity about what 'details' include and doesn't distinguish from sibling tools like 'search_notes' or 'create_note', which is a missed opportunity for clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention that 'get_note' is for retrieving a single note by ID, while 'search_notes' might be for multiple notes or filtering, leaving the agent to infer usage from context without explicit help.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_notesC

Search for notes in TriliumNext

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query (fulltext or structured, max 500 characters)
limitNoMaximum number of results to return

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool searches for notes but doesn't describe key behaviors like whether it's read-only (implied but not explicit), how results are returned (e.g., format, pagination), error conditions, or performance aspects like rate limits. This leaves significant gaps for an agent to understand the tool's operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete for a search tool. It doesn't explain what the search returns (e.g., note metadata, content snippets), how results are structured, or any behavioral nuances like sorting or filtering options. This makes it inadequate for an agent to fully understand the tool's context and usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the input schema already documents both parameters ('query' and 'limit') with details like constraints and defaults. The description adds no additional meaning beyond what the schema provides, such as examples of query syntax or result ordering, but doesn't need to compensate for gaps, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search for notes') and the target resource ('in TriliumNext'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'get_note' (which might retrieve a specific note) or mention what makes this search distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_note' or 'create_note'. It lacks context about prerequisites, such as whether notes must exist or be accessible, and doesn't mention any exclusions or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_noteC

Update the content of an existing note

ParametersJSON Schema
NameRequiredDescriptionDefault
noteIdYesThe ID of the note to update
contentYesThe new content for the note (max 1MB)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states it updates content without disclosing behavioral traits like permission requirements, whether the update overwrites or merges content, error handling, or rate limits. This is inadequate for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste, front-loading the key action and resource. It's appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a mutation tool with two parameters, the description is incomplete. It lacks details on behavior, return values, or error cases, making it insufficient for reliable agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('noteId' and 'content') adequately. The description adds no additional meaning beyond implying the tool uses these parameters, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update') and resource ('the content of an existing note'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'create_note' or 'get_note' beyond the basic verb, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'create_note' or 'get_note'. It lacks context about prerequisites (e.g., needing an existing note ID) or exclusions, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updates
    • First observedcreate_note
    • First observedget_note
    • First observedsearch_notes
    • First observedupdate_note
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific CRUD operations for notes: create_note for creation, get_note for retrieval, search_notes for searching, and update_note for updates. There is no overlap in functionality, making tool selection straightforward.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case, using clear action verbs (create, get, search, update) paired with the noun 'note' or 'notes'. This uniformity enhances readability and predictability.

Tool Count5/5

With 4 tools, the server is well-scoped for managing notes in TriliumNext, covering essential operations without being overly simplistic or bloated. Each tool serves a distinct and necessary function in the note lifecycle.

Completeness4/5

The tool set provides strong coverage for core note operations, including create, read, search, and update. A minor gap exists with no delete_note tool, which could limit full lifecycle management, but agents can still handle most workflows effectively.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Obsidian MCP

    takuya0206
    A
    license
    B
    quality
    F
    maintenance
    A Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.
    5
    4,785
    4
    ISC

  • triliumnext-mcp

    perfectra1n
    F
    license
    Not graded
    quality
    A
    maintenance
    A Model Context Protocol (MCP) server for interacting with TriliumNext via its ETAPI. Enables LLMs to create, read, update, and organize notes, including embedding images and files directly into note content.
    81
    65
    -

  • Trilium MCP Server

    lilaflo
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI clients to manage Trilium Notes with full CRUD operations, search, calendar integration, and system administration through the Model Context Protocol.
    18
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/RadonX/mcp-trilium'

If you have feedback or need assistance with the MCP directory API, please join our Discord server