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: Notion 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

Clone and install
git clone git@github.com:RadonX/mcp-trilium.git cd mcp-trilium npm install
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
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
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

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes with tests
Run the test suite: npm test
Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

TriliumNext - The note-taking application
Model Context Protocol - MCP specification
Claude Desktop - AI assistant with MCP support

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