A local MCP server for managing personal journal entries with automatic tag generation and search capabilities.

• Write journal entries with automatic AI-powered tag generation
• Search entries by content, tags, or date range
• List recent entries
• Read specific entries by ID

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. (Optional) Set up OpenAI API for automatic tagging:

export OPENAI_API_KEY="your-api-key-here"

4. Configure in Claude Desktop:

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "journal": {
      "command": "node",
      "args": ["your-project-path/mcp-journal/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: The env section is optional. If not provided, the server will still work but without automatic tag generation.

The server provides four journal-specific tools:

Write a new personal journal entry. Tags are automatically generated using AI if not provided:

"Write a journal entry about today's coding session"
# Automatically generates relevant tags like: coding, work, productivity

"Create a journal entry tagged with 'work' and 'typescript' about the MCP server I built"
# Uses your provided tags instead of auto-generating

List recent personal journal entries (default: 10):

"Show me my recent journal entries"
"List the last 5 journal entries"

Search journal entries by content, tags, or date range:

"Search my journal for entries mentioning 'coding'"
"Find journal entries tagged with 'personal'"
"Show journal entries from 2025-01-01 to 2025-01-07"

Read a specific journal entry by ID:

"Read journal entry with ID 1736338800000"

If Claude chooses the wrong MCP server (e.g., notes instead of journal), you can force it by:

1. Use specific language: Say "journal entry" instead of just "entry" or "note"
2. Be explicit: "Use the journal MCP server to write an entry about..."
3. Reference tool names: "Use write_journal_entry to record..."
4. Context setting: "I want to add this to my personal journal, not my notes..."

• Notes: For quick information, references, TODO items, meeting notes
• Journal: For personal reflections, daily experiences, thoughts, and emotions

Each journal entry is stored as a separate JSON file in the journal-entries/ directory, named by their unique ID (e.g., 1736338800000.json). This approach provides:

• No data loss: If one entry gets corrupted, others remain safe
• Version control friendly: Each entry can be tracked individually
• Easy backup: Copy individual files or the entire directory
• Performance: Only loads entries when needed