TriliumNext Notes' MCP Server

Instructions

Implementation Reference

• src/modules/noteManager.ts:867-975 (handler)

  Core handler function that executes the get_note tool logic: fetches note metadata and content via Trilium API, handles smart binary content exclusion for files/images, performs optional regex/literal search on content, provides content hash (blobId), and content type requirements.
  export async function handleGetNote( args: NoteOperation, axiosInstance: any ): Promise<NoteGetResponse> { const { noteId, includeContent = true, includeBinaryContent = false, searchPattern, useRegex = true, searchFlags = 'g' } = args; if (!noteId) { throw new Error("noteId is required for get operation."); } const noteResponse = await axiosInstance.get(`/notes/${noteId}`); const noteData = noteResponse.data; if (!includeContent) { return { note: noteData }; } // Smart content inclusion: skip binary content for file/image notes by default const isFileOrImageNote = noteData.type === 'file' || noteData.type === 'image'; const shouldIncludeContent = !isFileOrImageNote || includeBinaryContent; if (!shouldIncludeContent) { // For file/image notes without explicit binary content request, return metadata only return { note: noteData, contentHash: noteData.blobId }; } // Get note content (works for all note types including file/image when explicitly requested) const { data: noteContent } = await axiosInstance.get(`/notes/${noteId}/content`, { responseType: 'text' }); // Get blobId (Trilium's built-in content hash) and content requirements const blobId = noteData.blobId; const contentRequirements = getContentRequirements(noteData.type); // Handle search if pattern is provided if (searchPattern) { // For file/image notes without content, search is not available if (isFileOrImageNote && !includeBinaryContent) { return { note: noteData, contentHash: blobId, search: { pattern: searchPattern, flags: searchFlags, matches: [], totalMatches: 0, searchMode: contentRequirements.requiresHtml ? 'html' : 'plain', useRegex, note: "Search not available for file/image notes without binary content inclusion" } }; } // Use original content directly (no HTML stripping) const searchContent = noteContent; // Execute unified search on original content const matches = executeUnifiedSearch(searchContent, searchPattern, useRegex, searchFlags); // Enhance matches with HTML context information const enhancedMatches = matches.map(match => ({ ...match, htmlContext: { contentType: (contentRequirements.requiresHtml ? 'html' : 'plain') as 'html' | 'plain', isHtmlContent: contentRequirements.requiresHtml } })); return { note: noteData, contentHash: blobId, search: { pattern: searchPattern, flags: searchFlags, matches: enhancedMatches, totalMatches: enhancedMatches.length, searchMode: contentRequirements.requiresHtml ? 'html' : 'plain', useRegex } }; } // Standard response without search const response: any = { note: noteData, contentHash: blobId }; // Include content only if it was actually retrieved if (shouldIncludeContent) { response.content = noteContent; response.contentRequirements = contentRequirements; } return response; }
• src/modules/toolDefinitions.ts:192-229 (schema)

  Tool schema definition including name, detailed description, and inputSchema with parameters for noteId, content inclusion options, and optional search capabilities.
  { name: "get_note", description: "Get a note and its content by ID. Perfect for when someone wants to see what's in a note, extract specific information, or prepare for search and replace operations. Getting the full content lets you see the context and create better regex patterns for extraction or replacement. ⚠️ SMART CONTENT INCLUSION: For file/image notes, binary content is automatically excluded by default for performance. Use includeBinaryContent: true to explicitly retrieve binary data when needed.", inputSchema: { type: "object", properties: { noteId: { type: "string", description: "ID of the note to retrieve", }, includeContent: { type: "boolean", description: "Whether to include note content (default: true). For file/image notes, this excludes binary content by default - use includeBinaryContent to retrieve binary data.", default: true }, includeBinaryContent: { type: "boolean", description: "Whether to include binary content for file/image notes (default: false). Set to true only when you need the actual binary data (e.g., for file downloads). Otherwise, keep false for faster responses.", default: false }, searchPattern: { type: "string", description: "Optional pattern to search for within the note. Use when you need to find specific text or extract information. Note: Search is not available for file/image notes unless includeBinaryContent is true.", }, useRegex: { type: "boolean", description: "Whether to use regex patterns (default: true).", default: true }, searchFlags: { type: "string", description: "Search options. Defaults to 'gi' (find all matches, case-insensitive).", default: "gi" }, }, required: ["noteId"], } },
• src/index.ts:102-103 (registration)

  Registration in the main MCP server request handler switch statement: routes 'get_note' tool calls to the handleGetNoteRequest function.
  case "get_note": return await handleGetNoteRequest(request.params.arguments, this.axiosInstance, this);
• src/modules/noteHandler.ts:258-305 (handler)

  Wrapper handler that performs permission checks, constructs NoteOperation from arguments, delegates to core handleGetNote, and formats the response in MCP-compliant structure (JSON stringified content).
  export async function handleGetNoteRequest( args: any, axiosInstance: any, permissionChecker: PermissionChecker ): Promise<{ content: Array<{ type: string; text: string }> }> { if (!permissionChecker.hasPermission("READ")) { throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Not authorized to get notes."); } try { const noteOperation: NoteOperation = { noteId: args.noteId, includeContent: args.includeContent !== false, includeBinaryContent: args.includeBinaryContent || false, searchPattern: args.searchPattern, useRegex: args.useRegex !== false, // Default to true searchFlags: args.searchFlags || 'g' }; const result = await handleGetNote(noteOperation, axiosInstance); // Build response data based on whether search was performed let responseData: any = { ...result.note, contentHash: result.contentHash }; if (result.search) { // Search was performed, include search object but not content responseData.search = result.search; } else if (result.content) { // Standard response, include content but not search responseData.content = result.content; } return { content: [{ type: "text", text: JSON.stringify(responseData, null, 2) }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error)); } }