jrnl MCP Server

Instructions

Implementation Reference

• src/handlers/entryHandlers.ts:23-59 (handler)

  Core handler function that builds a search command using filters from params, executes it via JrnlExecutor, parses the JSON output, transforms entries to JournalEntry format, and returns entries and tag counts.
  export async function searchEntries( params: SearchEntriesParams, executor: JrnlExecutor, ): Promise<{ entries: JournalEntry[]; tags: Record<string, number> }> { const filters: SearchFilters = { from: params.from, to: params.to, tags: params.tags, contains: params.contains, limit: params.limit, starred: params.starred, }; const command = buildSearchCommand(filters, params.journal); const result = await executor.execute(command); try { const data = JSON.parse(result); // jrnl exports in a specific format, need to transform it const entries: JournalEntry[] = data.entries.map((entry: any) => ({ date: entry.date, time: entry.time || "", title: entry.title || "", body: entry.body || "", tags: entry.tags || [], starred: entry.starred || false, })); return { entries, tags: data.tags || {}, }; } catch (error) { throw new Error(`Failed to parse jrnl output: ${error}`); } }
• src/handlers/entryHandlers.ts:13-21 (schema)

  TypeScript interface defining the input parameters for the searchEntries tool.
  export interface SearchEntriesParams { from?: string; to?: string; tags?: string[]; contains?: string; limit?: number; starred?: boolean; journal?: string; }
• src/handlers/entryHandlers.ts:4-11 (schema)

  TypeScript interface defining the structure of journal entries returned by the tool.
  export interface JournalEntry { date: string; time: string; title: string; body: string; tags: string[]; starred: boolean; }
• src/index.ts:37-64 (registration)

  MCP tool registration including name, description, and input schema definition in the ListToolsRequestHandler.
  name: "search_entries", description: "Search and filter journal entries", inputSchema: { type: "object", properties: { from: { type: "string", description: 'Start date (e.g., "yesterday", "2024-01-01")', }, to: { type: "string", description: "End date" }, tags: { type: "array", items: { type: "string" }, description: "Tags to filter by", }, contains: { type: "string", description: "Text to search for" }, limit: { type: "number", description: "Maximum number of entries" }, starred: { type: "boolean", description: "Only show starred entries", }, journal: { type: "string", description: "Journal name (uses current/default if not specified)", }, }, }, },
• src/index.ts:154-166 (registration)

  Dispatcher case in CallToolRequestHandler that invokes the searchEntries handler with parameters and current journal.
  case "search_entries": return { content: [ { type: "text", text: JSON.stringify( await searchEntries({ ...args, journal } as any, executor), null, 2, ), }, ], };