jrnl MCP Server
The jrnl MCP Server provides read-only access to your jrnl command-line journal entries through Claude, enabling natural language interaction with your journal data.
Search and filter journal entries by date range (using flexible formats like "yesterday" or specific dates), tags, text content, starred status, or specific journals, with configurable result limits
List all tags with usage counts to understand tag frequency across your journals
Analyze tag co-occurrence to identify which tags frequently appear together in entries
Get journal statistics including analytics grouped by time period (day/week/month/year) with optional top tag inclusion
Manage multiple journals by listing all available journals and switching between them for subsequent operations
Integrate with Claude Desktop for seamless natural language querying and analysis of your journal data
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jrnl MCP Server search my journal entries from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
Related MCP server: Desktop Commander MCP
Installation
npm install
npm run build
npm link # Install globally as jrnl-mcp commandClaude 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 productionPublishing
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:
Click "Publishing access" or "Trusted publishers"
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
Update the version in
package.json:npm version patch # or minor, or majorPush the version commit and tag to GitHub:
git push && git push --tagsCreate a new release on GitHub:
Click "Draft a new release"
Select the tag you just pushed
Add release notes
Click "Publish release"
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
Build the project:
npm run buildUpdate your Claude Desktop config with the correct path
Restart Claude Desktop
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 toolsanalyze_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
Scored across 6 tools
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.
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.
With 6 tools, the server is well-scoped for a journal management system. It covers core operations without being bloated or insufficient.
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
Related MCP Connectors
A self-hostable feed of reminders, learnings and work that Claude and ChatGPT can read and write
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables Claude to persistently store, search, and manage text memories with tags in a local JSON file.1434 npmMIT
- AlicenseAqualityDmaintenanceA 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.191,287,096 npm6MIT
- AlicenseNot gradedqualityDmaintenanceA 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.19MIT
- AlicenseAqualityDmaintenanceAn 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.630 npm2MIT