A
licenseB
qualityD
maintenanceA Model Context Protocol server that enables Claude to persistently store, search, and manage text memories with tags in a local JSON file.
14
6
MIT
jrnl MCP Server
by yostos
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 Serversearch 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
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | Tags to analyze for co-occurrence | |
| journal | No | Journal name (uses current/default if not specified) |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It merely states 'Analyze which tags frequently appear together' without mentioning output format, data source, performance, or that it is a read operation. Critical details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the core purpose. There is no extraneous information, making it concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderately complex nature of analyzing tag co-occurrence (likely returning pairs and frequencies), the description is too sparse. No output schema exists, and the description fails to explain what the tool returns or how the journal parameter affects results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters having clear descriptions in the schema. The overall description adds no additional meaning beyond what the schema already provides, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Analyze') and resource ('tag co-occurrence'), clearly indicating it examines relationships between tags. However, it does not differentiate from sibling tools like list_tags or search_entries, which have distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as list_tags or search_entries. Usage is implied from the description but no when-not or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_statisticsC
Get journal statistics and analytics
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| journal | No | Journal name (uses current/default if not specified) | |
| timeGrouping | No | Group statistics by time period | |
| includeTopTags | No | Include top tags in statistics |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose any behavioral traits beyond the basic action. There is no mention of side effects, performance, or data sensitivity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is somewhat under-specified and could benefit from more detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is minimal. It fails to explain what kind of statistics are returned or how to interpret the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning to the parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get journal statistics and analytics' clearly states the verb and resource, but it is generic and does not distinguish this tool from siblings like 'analyze_tag_cooccurrence'. However, the purpose is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusion criteria. The description offers no context for usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_journalsB
List all available journals
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'list all available journals' but does not reveal behavioral traits like output format, pagination, or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, directly conveys the purpose. Appropriate length for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should clarify what is returned (e.g., journal names or IDs). It does not, leaving agents guessing about the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Baseline is 4. Description adds no additional parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (journals) with scope (all available). It is distinct from sibling tools like list_tags or search_entries, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_tagsA
List all tags with their usage counts
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| journal | No | Journal name (uses current/default if not specified) |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read-only operation by using 'list', but does not explicitly state safety or side effects. Minimal behavioral context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no wasted words. All essential information is front-loaded and efficiently communicated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description adequately states the function and output. However, it could optionally mention that results are unordered or unaffected by other filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional parameter 'journal', which has a clear description. The tool description adds no further parameter information, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all tags with their usage counts' clearly states the verb (list), resource (tags), and additional detail (usage counts). It is distinct from sibling tools like analyze_tag_cooccurrence and list_journals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the purpose is straightforward. The description implies its usage context as a simple listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_entriesC
Search and filter journal entries
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | Start date (e.g., "yesterday", "2024-01-01") | |
| to | No | End date | |
| tags | No | Tags to filter by | |
| contains | No | Text to search for | |
| limit | No | Maximum number of entries | |
| starred | No | Only show starred entries | |
| journal | No | Journal name (uses current/default if not specified) |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic purpose, failing to mention details like sorting, pagination, or side effects. The schema parameter descriptions cover behavior partially, but the description adds no extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 4 words, which is efficient but under-specified. It sacrifices necessary detail for brevity, making it barely adequate. It is front-loaded but lacks substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain output format, sorting, or how filters combine. Essential context for effective use is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents each parameter. The description adds no additional parameter semantics beyond the verb 'search and filter', which is already implied. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search and filter journal entries' clearly states the verb (search/filter) and resource (journal entries). It is clear but does not distinguish from sibling tools like list_journals or get_statistics, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool versus alternatives, nor does it mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_journalB
Set the active journal for subsequent operations
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| journalName | Yes | Name of the journal to set as active |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It fails to mention whether the operation is destructive, whether it requires authentication, whether it is reversible, or if it has side effects like changing global state. The description is too minimal for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence, 8 words) and front-loads the action and object. While it is efficient, it could include a bit more context without becoming verbose, such as mentioning that the active journal persists across operations. Still, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description does not explain the implications of setting the active journal, such as its persistence, validation of journal names, or how it affects sibling tools like 'search_entries'. The description feels incomplete for a tool that changes state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a description for the parameter 'journalName', achieving 100% schema coverage. The tool description does not add any additional meaning or constraints beyond what the schema states. According to the rules, baseline is 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and the resource ('active journal'), and implies the tool's role in setting context for subsequent operations. It distinguishes itself from sibling tools like 'list_journals' (which lists journals) and 'search_entries' (which searches entries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when a journal must be set before other operations or when it should not be used (e.g., if a journal is already active). The description lacks any context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
- First observed
analyze_tag_cooccurrence - First observed
get_statistics - First observed
list_journals - First observed
list_tags - First observed
search_entries - First observed
set_journal
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
ActivityInactive
ResponsivenessNo issues
Related MCP Connectors
Private journal MCP server to search, analyze, and create Dabble Me entries securely via OAuth.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
A business back-office for Claude — tasks, deals, customers, publishing and tracked links.
Related MCP Servers
- 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.1995,6356MIT
- 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.18MIT
- 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.6152MIT