trilium-mcp by lilaflo - MCP Server

Trilium MCP Server

A comprehensive Model Context Protocol (MCP) server for Trilium Notes integration, providing complete note management functionality through MCP-compatible AI clients.

🚀 Production Ready • 🔧 12 API Endpoints • 📊 Comprehensive Testing • 🏥 Health Monitoring

Live Server: https://your-trilium-server.example.com/mcp

✨ Features

Complete Note Management: Create, read, update, delete, and search notes
Rich Content Support: HTML content with formatting and attachments
Calendar Integration: Day, week, and month notes with automatic organization
Advanced Search: Full-text search with filtering and structured results
File Attachments: Base64-encoded file attachment support
System Operations: Backup creation, export functionality, and system info
Verbose Logging: Comprehensive request tracking and health monitoring
Production Deployment: HTTPS endpoint with authentication and error handling

🎯 API Endpoints (12 Total)

✅ Core Note Operations (6 endpoints)

1. `create_note` - Create New Notes

Create notes with rich content and hierarchical organization.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "parentId": "root",
      "title": "🚀 Project Ideas",
      "content": "<h1>My Project Ideas</h1><ul><li>AI-powered note taking</li><li>Collaborative documentation</li></ul>",
      "type": "text"
    }
  }
}

Parameters:

parentId (string): Parent note ID (use "root" for top-level)
title (string): Note title
content (string, optional): HTML content
type (string, default: "text"): Note type

2. `get_note` - Retrieve Note Metadata

Get complete note information including relationships and attributes.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_note",
    "arguments": {
      "noteId": "SeJAf97IhUVM"
    }
  }
}

Parameters:

noteId (string): ID of the note to retrieve

3. `get_note_content` - Get Note Content

Retrieve the raw HTML content of a note.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_note_content",
    "arguments": {
      "noteId": "SeJAf97IhUVM"
    }
  }
}

4. `update_note` - Update Note Title

Update note title and metadata (content updated separately).

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "update_note",
    "arguments": {
      "id": "SeJAf97IhUVM",
      "title": "📝 Updated Project Ideas"
    }
  }
}

Parameters:

id (string): Note ID to update
title (string, optional): New title
content (string, optional): Use update_note_content instead

5. `update_note_content` - Update Note Content

Update the HTML content of a note directly.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "update_note_content",
    "arguments": {
      "noteId": "SeJAf97IhUVM",
      "content": "<h1>Updated Content</h1><p>This content has been updated via MCP.</p>"
    }
  }
}

5. `move_note` - Move Notes

Move a note to a different parent in the note tree structure.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "move_note",
    "arguments": {
      "noteId": "SeJAf97IhUVM",
      "parentId": "8BQtwgpvcO3d",
      "position": 10
    }
  }
}

Parameters:

noteId (string): ID of the note to move
parentId (string): ID of the new parent note
position (number, optional): Position under the new parent

6. `delete_note` - Delete Notes

Remove a note from Trilium (handles empty API responses).

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "delete_note",
    "arguments": {
      "noteId": "fnr2ZfZH2uVo"
    }
  }
}

🔍 Search Operations (1 endpoint)

7. `search_notes` - Advanced Search

Full-text search with structured results and filtering options.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "query": "project documentation",
      "limit": 10,
      "format": "structured"
    }
  }
}

Parameters:

query (string): Search query
limit (number, 1-100, default: 20): Max results
format ("raw" | "structured", default: "structured"): Output format

📅 Calendar Integration (3 endpoints)

8. `get_day_note` - Daily Notes

Get or create daily notes for calendar integration.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_day_note",
    "arguments": {
      "date": "2025-09-29"
    }
  }
}

9. `get_week_note` - Weekly Notes ⚠️

Get weekly notes (requires specific date format).

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "get_week_note",
    "arguments": {
      "date": "2025-W39"
    }
  }
}

10. `get_month_note` - Monthly Notes

Get or create monthly notes with child relationships.

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_month_note",
    "arguments": {
      "month": "2025-09"
    }
  }
}

11. `get_inbox_note` - Inbox Notes

Get the inbox note for a specific date (returns daily note).

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "get_inbox_note",
    "arguments": {
      "date": "2025-09-29"
    }
  }
}

📎 File Operations (1 endpoint)

12. `create_attachment` - File Attachments

Create file attachments with base64-encoded content.

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "create_attachment",
    "arguments": {
      "ownerId": "SeJAf97IhUVM",
      "title": "document.txt",
      "role": "file",
      "mime": "text/plain",
      "content": "VGhpcyBpcyBhIHRlc3QgZmlsZSBjb250ZW50",
      "position": 10
    }
  }
}

Parameters:

ownerId (string): Note ID that owns the attachment
title (string): Filename
role (string, default: "file"): Attachment role
mime (string, default: "text/plain"): MIME type
content (string): Base64-encoded file content
position (number, optional): Attachment position

🛠️ System Operations (3 endpoints)

13. `get_app_info` - System Information

Get comprehensive Trilium instance information.

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "get_app_info",
    "arguments": {}
  }
}

Response includes:

Trilium version (0.98.0)
Node.js version (v22.18.0)
Database version (233)
Build information and data directory

14. `export_note` - Export Notes ⚠️

Export note subtrees as ZIP files (binary response handling needed).

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "export_note",
    "arguments": {
      "noteId": "8BQtwgpvcO3d",
      "format": "html"
    }
  }
}

Parameters:

noteId (string): Note ID to export (use "root" for full export)
format ("html" | "markdown", default: "html"): Export format

15. `create_backup` - Database Backup ⚠️

Create database backups (empty response handling needed).

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "create_backup",
    "arguments": {
      "backupName": "mcp-backup-2025-09-29"
    }
  }
}

🎯 Status Summary

Status	Count	Tools
✅ Working	13/15	All core operations, search, calendar, attachments, system info
⚠️ Minor Issues	2/15	`get_week_note` (date format), `export_note` (binary handling)

Overall Grade: A- (87% success rate)

🚀 Quick Start

For AI Clients (Recommended)

Copy configuration from mcp-server-config.json:

{
  "mcpServers": {
    "trilium": {
      "command": "curl",
      "args": [
        "-X",
        "POST",
        "https://your-trilium-server.example.com/mcp",
        "-H",
        "Content-Type: application/json",
        "-H",
        "Accept: application/json, text/event-stream",
        "--data-binary",
        "@-"
      ]
    }
  }
}

Import into your AI client:
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
- Other MCP clients: Use the universal configuration
Start using - All 15 tools will be available immediately!

Direct HTTP Testing

# Test note creation
curl -X POST https://your-trilium-server.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_note",
      "arguments": {
        "parentId": "root",
        "title": "API Test Note",
        "content": "<h1>Hello from MCP!</h1><p>This note was created via the API.</p>"
      }
    }
  }'

# Test search functionality
curl -X POST https://your-trilium-server.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_notes",
      "arguments": {
        "query": "API Test",
        "limit": 5,
        "format": "structured"
      }
    }
  }'

# Get system information
curl -X POST https://your-trilium-server.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_app_info",
      "arguments": {}
    }
  }'

🏗️ Local Development

Prerequisites

Node.js 18+
pnpm package manager
Trilium Notes instance with ETAPI enabled

Setup

Clone and install:

git clone <repository-url>
cd trilium-mcp
pnpm install

Configure environment:

cp .env.example .env
# Edit .env with your Trilium URL and token

Start development server:

pnpm dev  # Auto-reload enabled
# or
pnpm start  # Production mode

Health check:

curl http://localhost:3000/health

Environment Variables

Variable	Description	Required	Default
`TRILIUM_URL`	Trilium ETAPI URL (include `/etapi` path)	✅	-
`TRILIUM_TOKEN`	ETAPI authentication token	✅	-
`PORT`	HTTP server port	❌	3000
`NODE_ENV`	Environment mode	❌	development

📊 Production Features

🔍 Comprehensive Logging

Request tracking: Unique IDs for every MCP request with timing
ETAPI monitoring: All Trilium API calls logged with request/response details
Health monitoring: System stats every 30 seconds (memory, connections, uptime)
Error handling: Full stack traces and detailed error messages
Connection tracking: Active/total connection counts with lifecycle logging

🏥 Health Monitoring

# View server health
curl https://my-own-trilium-mcp.fly.dev/health

# Monitor deployment logs
fly logs -a your-app-name

🔒 Security

HTTPS deployment with proper TLS
ETAPI authentication with Basic Auth
CORS enabled for cross-origin requests
Request validation with MCP protocol compliance
Error sanitization without sensitive data leakage

📈 Performance Metrics

Based on comprehensive testing:

Response Times: 100-300ms average for most operations
Memory Usage: ~99MB RSS, stable memory footprint
Connection Handling: Proper cleanup and resource management
Uptime: Production-stable with comprehensive error handling
Success Rate: 13/15 endpoints (87%) fully working

🧪 Testing Results

The server has been comprehensively tested with real-world scenarios:

✅ Created nested folder structure with rich HTML content ✅ All CRUD operations tested with actual data ✅ Calendar integration verified with daily/monthly notes ✅ File attachments tested with base64 encoding ✅ Search functionality confirmed with structured results ✅ System operations validated including backups and info retrieval

See FINAL-TEST-RESULTS.md for complete testing documentation.

🐛 Known Issues & Workarounds

⚠️ Minor Issues (2/15 endpoints)

get_week_note: Requires specific date format (e.g., "2025-W39" instead of "2025-09-29")
export_note: Returns binary ZIP data but expects JSON (export works, response handling needs improvement)

💡 Recommended Usage Patterns

✅ Note management: Create, read, update, search notes (fully working)
✅ Content editing: Full HTML content support with rich formatting
✅ Calendar integration: Use daily and monthly notes (weekly needs format fix)
✅ File attachments: Base64 encoded file attachments work perfectly
✅ System monitoring: Get Trilium instance information
⚠️ Backup/Export: Works but needs better binary response handling

🔗 Additional Resources

Complete API Documentation: MCP-USAGE.md
Testing Results: FINAL-TEST-RESULTS.md
Configuration Files: Multiple MCP client configs provided
Trilium Notes - The note-taking application
Model Context Protocol - The underlying protocol
Trilium ETAPI Docs - External API documentation

📄 License

MIT License - see file for details.

Ready to use! 🎉 Import the configuration files into your favorite MCP-compatible AI client and start managing your Trilium notes with AI assistance.

lilaflo/trilium-mcp

Trilium MCP Server

✨ Features

🎯 API Endpoints (12 Total)

✅ Core Note Operations (6 endpoints)

1. create_note - Create New Notes

2. get_note - Retrieve Note Metadata

3. get_note_content - Get Note Content

4. update_note - Update Note Title

5. update_note_content - Update Note Content

5. move_note - Move Notes

6. delete_note - Delete Notes

🔍 Search Operations (1 endpoint)

7. search_notes - Advanced Search

📅 Calendar Integration (3 endpoints)

8. get_day_note - Daily Notes

9. get_week_note - Weekly Notes ⚠️

10. get_month_note - Monthly Notes

11. get_inbox_note - Inbox Notes

📎 File Operations (1 endpoint)

12. create_attachment - File Attachments

🛠️ System Operations (3 endpoints)

13. get_app_info - System Information

14. export_note - Export Notes ⚠️

15. create_backup - Database Backup ⚠️

🎯 Status Summary

🚀 Quick Start

For AI Clients (Recommended)

Direct HTTP Testing

🏗️ Local Development

Prerequisites

Setup

Environment Variables

📊 Production Features

🔍 Comprehensive Logging

🏥 Health Monitoring

🔒 Security

📈 Performance Metrics

🧪 Testing Results

🐛 Known Issues & Workarounds

⚠️ Minor Issues (2/15 endpoints)

💡 Recommended Usage Patterns

🔗 Additional Resources

📄 License

1. `create_note` - Create New Notes

2. `get_note` - Retrieve Note Metadata

3. `get_note_content` - Get Note Content

4. `update_note` - Update Note Title

5. `update_note_content` - Update Note Content

5. `move_note` - Move Notes

6. `delete_note` - Delete Notes

7. `search_notes` - Advanced Search

8. `get_day_note` - Daily Notes

9. `get_week_note` - Weekly Notes ⚠️

10. `get_month_note` - Monthly Notes

11. `get_inbox_note` - Inbox Notes

12. `create_attachment` - File Attachments

13. `get_app_info` - System Information

14. `export_note` - Export Notes ⚠️

15. `create_backup` - Database Backup ⚠️