Private Journal MCP Server

A comprehensive MCP (Model Context Protocol) server that provides Claude with private journaling and semantic search capabilities for processing thoughts, feelings, and insights.

Features

Journaling

Multi-section journaling: Separate categories for feelings, project notes, user context, technical insights, and world knowledge
Dual storage: Project notes stay with projects, personal thoughts in user home directory
Timestamped entries: Each entry automatically dated with microsecond precision
YAML frontmatter: Structured metadata for each entry

Search & Discovery

Semantic search: Natural language queries using local AI embeddings
Vector similarity: Find conceptually related entries, not just keyword matches
Local AI processing: Uses @xenova/transformers - no external API calls required
Automatic indexing: Embeddings generated for all entries on startup and ongoing

Privacy & Performance

Completely private: All processing happens locally, no data leaves your machine
Fast operation: Optimized file structure and in-memory similarity calculations
Robust fallbacks: Intelligent path resolution across platforms

Tech Stack

Core Technologies

Node.js 18+ - Runtime environment with modern JavaScript features
TypeScript 5.0+ - Type-safe development with strict configuration
MCP SDK 0.4.0 - Official Model Context Protocol implementation
@xenova/transformers - Local AI models for semantic embeddings (no external APIs)

AI & Search

Semantic Embeddings - Multiple model options (MiniLM, DistilRoBERTa, MPNet)
Vector Similarity - Local cosine similarity calculations
Natural Language Search - Query understanding without external services

Development & Quality

Jest - Comprehensive testing framework with mocks
Biome - Modern linting and formatting
Oxlint - Additional code quality checks
GitHub Actions - Continuous integration and testing

Storage & Architecture

Markdown + YAML - Human-readable entries with structured metadata
Hierarchical File System - Date-based organization with microsecond precision
Cross-Platform - Windows, macOS, and Linux support

For detailed architectural decisions, see ARCHITECTURE.md.

Installation

npm install -g private-journal-mcp

Or install locally:

npm install private-journal-mcp

Usage

Basic Usage

private-journal-mcp

This creates journal entries in .private-journal/ in the current working directory.

Custom Journal Path

private-journal-mcp --journal-path /path/to/my/journal

Embedding Model Configuration

You can customize the AI model used for generating semantic embeddings:

export JOURNAL_EMBEDDING_MODEL="Xenova/all-distilroberta-v1"

Available Models:

Xenova/all-MiniLM-L6-v2 (default) - Fast, 384 dimensions, good general performance
Xenova/all-distilroberta-v1 - Larger, 768 dimensions, better accuracy
Xenova/paraphrase-MiniLM-L6-v2 - Optimized for paraphrase detection
Xenova/all-mpnet-base-v2 - High quality, 768 dimensions, slower but more accurate

The embedding model affects:

Local search quality - More sophisticated models provide better semantic understanding
Vector dimensions - Impacts remote server storage and search capabilities
Processing speed - Larger models are slower but more accurate
Memory usage - Bigger models require more RAM

Remote Server Integration

To enable optional remote posting of journal entries to a team server, set these environment variables:

export REMOTE_JOURNAL_SERVER_URL="https://api.yourteam.com"
export REMOTE_JOURNAL_TEAMID="your-team-id"
export REMOTE_JOURNAL_APIKEY="your-api-key"

When configured, journal entries will be posted to your remote server in addition to being saved locally. Local journaling always takes priority - if the remote posting fails, the local entry is still saved.

Remote-Only Mode

For teams using a backend server as the single source of truth, enable remote-only mode to skip local file storage entirely:

export REMOTE_JOURNAL_ONLY="true"

In remote-only mode:

No local storage - entries go directly to the backend server
Server-side search - all search queries use the backend API
Error handling - journal operations fail if server is unavailable
Team collaboration - automatic sharing across team members
Centralized AI - semantic search powered by backend infrastructure

Remote Payload Format