Skip to main content
Glama
jrnl MCP Server
by yostos

jrnl MCP Server

License: MIT Node.js Claude jrnl

A Model Context Protocol (MCP) server that provides read-only access to jrnl (command-line journal) entries.

Architecture Documentation - System design and component overview

Prerequisites

  • Node.js 18 or higher

  • jrnl installed and configured (pip install jrnl)

Related MCP server: Desktop Commander MCP

Installation

npm install
npm run build
npm link  # Install globally as jrnl-mcp command

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration

{
  "mcpServers": {
    "jrnl": {
      "command": "jrnl-mcp"
    }
  }
}

Note: If you installed via npm link, the command will be globally available. For local development without global installation, use:

{
  "mcpServers": {
    "jrnl": {
      "command": "node",
      "args": ["<path-to-project>/dist/index.js"]
    }
  }
}

Available Tools

  • search_entries - Search journal entries with filters

  • list_tags - List all tags with usage counts

  • get_statistics - Get journal statistics

  • analyze_tag_cooccurrence - Analyze tag co-occurrences

  • list_journals - List available journals

  • set_journal - Switch to a different journal

Development

npm run format  # Format code
npm run lint    # Run linter
npm test        # Run tests
npm run build   # Build for production

Publishing

This package uses GitHub Actions with npm Trusted Publishing (OIDC) for automated publishing. No npm tokens required!

Initial Setup (One-time)

Configure npm Trusted Publishing for this package:

  1. Go to https://www.npmjs.com/package/jrnl-mcp/access

  2. Click "Publishing access" or "Trusted publishers"

  3. Add a new trusted publisher:

    • Provider: GitHub Actions

    • Repository owner: yostos

    • Repository name: jrnl-mcp

    • Workflow name: publish.yml

    • Environment: (leave blank)

Publishing a New Version

  1. Update the version in package.json:

    npm version patch  # or minor, or major
  2. Push the version commit and tag to GitHub:

    git push && git push --tags
  3. Create a new release on GitHub:

  4. GitHub Actions will automatically:

    • Run tests

    • Build the package

    • Publish to npm with provenance (using OIDC, no tokens needed!)

The published package will have attestations that prove it was built from your GitHub repository.

Testing with Claude Desktop

  1. Build the project: npm run build

  2. Update your Claude Desktop config with the correct path

  3. Restart Claude Desktop

  4. Test by asking Claude to search your journal entries

Example prompts:

  • "Use jrnl to show me my journal entries from last week"

  • "Using jrnl, what tags am I using in my journal?"

  • "Can you use jrnl to show me statistics about my journal?"

  • "Search my journal entries for entries tagged with @work using jrnl"

Available Tools

6 tools
analyze_tag_cooccurrenceB

Analyze which tags frequently appear together

Inputs: tags (required), journal.

get_statisticsC

Get journal statistics and analytics

Inputs: journal, timeGrouping, includeTopTags.

list_journalsB

List all available journals

Inputs: no named parameters.

list_tagsA

List all tags with their usage counts

Inputs: journal.

search_entriesC

Search and filter journal entries

Inputs: from, to, tags, contains, +3 more.

set_journalB

Set the active journal for subsequent operations

Inputs: journalName (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: analyzing tag co-occurrence, getting statistics, listing journals, listing tags, searching entries, and setting the active journal. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., analyze_tag_cooccurrence, list_journals). No mixing of styles or ambiguous verbs.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a journal management system. It covers core operations without being bloated or insufficient.

    Completeness2/5

    The tool set is limited to read operations and one configuration action (set_journal). Missing essential write operations like creating, updating, or deleting entries and journals, which are expected for a journal management server.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.
      19
      1,287,096 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Message Control Protocol server that enables Claude Desktop and other applications to interact with Day One journals, allowing automated journal entry creation through a simple API.
      19
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that integrates with Claude Desktop for managing personal journal entries, providing both a web viewer for browsing journals and tools for adding, searching, and analyzing journal content.
      6
      30 npm
      2
      MIT