Private Journal MCP Server

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

Features

Journaling

• Multi-section journaling: Separate categories for reflections, observations, 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

Installation

This server is run directly from GitHub using npx - no installation required.

MCP Configuration

Claude Code (One-liner)

claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:obra/private-journal-mcp"]}' -s user

Manual Configuration

Add to your MCP settings (e.g., Claude Desktop configuration):

{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"]
    }
  }
}

The server will automatically find a suitable location for the journal files.

Configuration

PRIVATE_JOURNAL_PATH environment variable

Set PRIVATE_JOURNAL_PATH to override all journal storage to a single directory. This is useful for containerized deployments where the default home directory resolution doesn't apply:

{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"],
      "env": {
        "PRIVATE_JOURNAL_PATH": "/data/journals"
      }
    }
  }
}

When set, both project and user journals are written to the specified path, bypassing all fallback resolution logic.

--journal-path CLI argument

You can also set the project journal path via CLI argument:

npx github:obra/private-journal-mcp --journal-path /path/to/journals

This only overrides the project journal path. The user journal path still resolves via PRIVATE_JOURNAL_PATH or the default home directory logic.

MCP Tools

The server provides comprehensive journaling and search capabilities:

process_thoughts

Multi-section private journaling with these optional categories:

• reflections: Integrated thinking — what you noticed, felt, understood, or processed
• observations: Short, discrete noticings — one or two sentences each
• project_notes: Technical insights specific to current project
• user_context: Notes about collaborating with humans
• technical_insights: General software engineering learnings
• world_knowledge: Domain knowledge and interesting discoveries

search_journal

Semantic search across all journal entries:

• query (required): Natural language search query
• limit: Maximum results (default: 10)
• type: Search scope - 'project', 'user', or 'both' (default: 'both')
• sections: Filter by specific categories

read_journal_entry

Read full content of specific entries:

• path (required): File path from search results

list_recent_entries

Browse recent entries chronologically:

• limit: Maximum entries (default: 10)
• type: Entry scope - 'project', 'user', or 'both' (default: 'both')
• days: Days back to search (default: 30)

... View full README on GitHub