trilium-mcp-server

v0.1.6

Published

9 days ago

Model Context Protocol server for Trilium Notes ETAPI

Downloads

516

0High
0Medium
0Low

paerrin

mcp model-context-protocol trilium trilium-notes etapi knowledge-base

Trilium MCP Server

A Model Context Protocol (MCP) server for Trilium Notes, enabling LLMs to interact with your Trilium knowledge base through the ETAPI.

Features

Core Functionality

✅ Complete Note Management: Create, read, update, and delete notes
✅ Powerful Search: Search notes using Trilium's advanced query syntax
✅ Branch Operations: Manage note clones and hierarchies
✅ Attributes: Add and manage labels and relations
✅ Attachments: List and manage note attachments
✅ Daily Notes: Access day notes and inbox for quick capture
✅ Backup: Create database backups
✅ Multi-Instance Support: Manage multiple Trilium instances (test, personal, blog, etc.)
✅ 24 Tools Total: Comprehensive coverage of ETAPI endpoints

Quality & Reliability

✅ Type Safety: Full TypeScript with runtime validation via Zod
✅ Request Timeouts: Configurable timeout (default 30s) prevents hanging requests
✅ Smart Error Handling: Clear, actionable error messages with proper HTTP status codes
✅ Configuration Validation: URL and API token validation on startup
✅ Graceful Degradation: Handles version-specific API differences

Prerequisites

Node.js 18.0.0 or higher
Trilium Notes 0.50 or higher (TriliumNext recommended)
ETAPI Token from your Trilium instance

Installation

# Clone or navigate to the directory
cd /trilium_mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Multi-Instance Setup (Recommended)

Configure multiple Trilium instances in config/instances.json:

{
  "instances": {
    "test": {
      "name": "Trilium Test Instance",
      "description": "Testing and development instance",
      "serverUrl": "http://localhost:8080",
      "apiToken": "your-test-token-here",
      "timeout": 30000
    },
    "personal": {
      "name": "Personal Notes",
      "description": "Private personal knowledge base",
      "serverUrl": "http://localhost:37840",
      "apiToken": "your-personal-token-here"
    },
    "blog": {
      "name": "Public Blog",
      "description": "Public-facing blog content",
      "serverUrl": "https://blog.example.com",
      "apiToken": "your-blog-token-here"
    }
  }
}

Configuration Options:

name (required): Human-readable instance name
description (required): Instance purpose/description
serverUrl (required): Trilium server URL (must be http:// or https://)
apiToken (required): ETAPI authentication token (minimum 20 characters)
timeout (optional): Request timeout in milliseconds (default: 30000)

See MULTI_INSTANCE.md for complete multi-instance configuration guide.

Getting Your ETAPI Tokens

Open Trilium Notes
Go to Options → ETAPI
Create a new token
Add it to config/instances.json

Usage

Running the MCP Server

# Build first (only needed once or after code changes)
npm run build

# Run specific instance
npm run start:test      # Test instance
npm run start:personal  # Personal notes
npm run start:blog      # Blog instance

Testing with MCP Inspector

# Test specific instance
npm run inspector:test      # Test instance
npm run inspector:personal  # Personal instance
npm run inspector:blog      # Blog instance

This will start the MCP Inspector, allowing you to test all available tools interactively.

Using with Claude Desktop

Add all instances to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "trilium-test": {
      "command": "node",
      "args": [
        "/path/to/trilium-mcp-server/dist/index.js",
        "--instance=test"
      ]
    },
    "trilium-personal": {
      "command": "node",
      "args": [
        "/path/to/trilium-mcp-server/dist/index.js",
        "--instance=personal"
      ]
    },
    "trilium-blog": {
      "command": "node",
      "args": [
        "/path/to/trilium-mcp-server/dist/index.js",
        "--instance=blog"
      ]
    }
  }
}

A template is provided in claude_desktop_config.json - copy and customize as needed.

Available Tools

Core Note Operations

| Tool | Description | |------|-------------| | trilium_create_note | Create a new note with title, type, and content | | trilium_get_note | Get note metadata (title, dates, type, etc.) | | trilium_get_note_content | Retrieve note content | | trilium_update_note | Update note properties | | trilium_update_note_content | Update note content | | trilium_delete_note | Delete a note (move to trash) |

Search & Discovery

| Tool | Description | |------|-------------| | trilium_search_notes | Search using Trilium query syntax (#labels, fulltext) | | trilium_get_day_note | Get daily note for a specific date | | trilium_get_inbox_note | Get inbox note for quick capture |

Branch Operations (Clones)

| Tool | Description | |------|-------------| | trilium_create_branch | Clone note to a new location | | trilium_get_branch | Get branch information | | trilium_update_branch | Update branch properties | | trilium_delete_branch | Remove branch (keeps note in other locations) |

Attributes (Labels & Relations)

| Tool | Description | |------|-------------| | trilium_create_attribute | Add label or relation to note | | trilium_get_attributes | List all attributes for a note | | trilium_get_attribute | Get specific attribute | | trilium_update_attribute | Update attribute value | | trilium_delete_attribute | Delete an attribute |

Attachments

| Tool | Description | |------|-------------| | trilium_list_attachments | List note attachments | | trilium_get_attachment | Get attachment metadata | | trilium_delete_attachment | Delete an attachment |

Utilities

| Tool | Description | |------|-------------| | trilium_backup | Create database backup | | trilium_app_info | Get server version and info |

Example Usage

Creating a Note

{
  "name": "trilium_create_note",
  "arguments": {
    "parentNoteId": "root",
    "title": "My New Note",
    "type": "text",
    "content": "This is the note content",
    "attributes": [
      {
        "type": "label",
        "name": "priority",
        "value": "high"
      }
    ]
  }
}

Searching Notes

{
  "name": "trilium_search_notes",
  "arguments": {
    "query": "#todo AND #urgent",
    "limit": 20,
    "orderBy": "dateModified"
  }
}

Getting Daily Note

{
  "name": "trilium_get_day_note",
  "arguments": {
    "date": "2025-12-21"
  }
}

Search Syntax

Trilium supports powerful search queries:

Labels: #todo, #project, #priority=high
Fulltext: note.content*=keyword
Logical: #todo AND #urgent, #work OR #personal
Note properties: note.type=code, note.mime=application/json
Dates: note.dateModified>=MONTH-1

See Trilium Search Documentation for more details.

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Test with inspector
npm run inspector

Project Structure

trilium_mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── etapi-client.ts   # ETAPI HTTP client
│   ├── types.ts          # TypeScript type definitions
│   └── schemas.ts        # Zod validation schemas
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Error Handling

The server provides clear, actionable error messages with proper HTTP status codes:

401 Unauthorized: "Invalid ETAPI token. Get token from Options → ETAPI in Trilium"
404 Not Found: "Resource not found at {path}. The note/branch/attribute may have been deleted"
400 Bad Request: Includes validation errors with suggestions
408 Request Timeout: "Request timeout after {timeout}ms. The Trilium server may be slow or unreachable"
500 Network Error: Detailed network error information for troubleshooting

Configuration Validation:

Invalid URL format: "Instance has invalid serverUrl format: {url}"
Invalid protocol: "Must be http:// or https://, got: {protocol}"
Invalid token: "apiToken is too short. Please check your ETAPI token"

Recent Improvements

v0.1.0 Enhancements (December 2025)

✅ Request Timeout Support: Configurable timeout prevents hanging requests (default: 30s)
✅ Enhanced Type Safety: Replaced any types with proper TypeScript types and type guards
✅ Configuration Validation: URL format and API token validation on startup
✅ Improved Error Handling: Better error messages with proper type checking
✅ Code Documentation: JSDoc comments on all public API methods
✅ Code Cleanup: Removed unused code and improved maintainability
✅ Comprehensive Testing: 100% test pass rate with automated test suite

Contributing

Contributions welcome!

License

MIT

Resources

Author

Paerrin with Claude Code

Built with ❤️ for the Trilium community