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.
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
.envfile 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
.envfile
-
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 notesPOST /create-note- Create noteGET /notes/{id}- Get note detailsPUT /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 highlightingfile- File attachmentsimage- Image notessearch- Saved searchesbook- Book/chapter organizationrelationMap- Visual relation mapscanvas- 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_URLin.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