jrnl MCP Server

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)

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:

   • Go to https://github.com/yostos/jrnl-mcp/releases
   • Click "Draft a new release"
   • Select the tag you just pushed
   • Add release notes
   • Click "Publish release"

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"