Private Journal MCP Server

by obra

398 stars

416 downloads

Not rated

GitHub

Other

About

A lightweight MCP server that provides Claude with a private journaling capability to process feelings and thoughts

Details

Author: obra
GitHub stars: 398
Downloads: 416
Categories: Other

- Multi-section journaling with six optional categories (reflections, observations, project_notes, user_context, technical_insights, world_knowledge)
- Semantic search using local AI embeddings (no external API calls)
- Automatic indexing of all entries on startup and ongoing
- Completely private; all processing stays on your machine
- Dual storage: project notes stay with the project, personal thoughts in user home directory
- Timestamped entries with YAML frontmatter and microsecond precision

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Private Journal MCP Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Run the server directly from GitHub using npx with no installation required. Add it to your MCP settings (e.g., Claude Desktop configuration) by specifying "command": "npx" and "args": ["github:obra/private-journal-mcp"]. Optionally set the PRIVATE_JOURNAL_PATH environment variable or the --journal-path CLI argument to override the storage location.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

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)

File Structure

Project Journal (per project)

.private-journal/
├── 2025-05-31/
│   ├── 14-30-45-123456.md          # Project notes entry
│   ├── 14-30-45-123456.embedding   # Search index
│   └── ...

User Journal (global)

~/.private-journal/
├── 2025-05-31/
│   ├── 14-32-15-789012.md          # Personal thoughts entry
│   ├── 14-32-15-789012.embedding   # Search index
│   └── ...

Entry Format

Each markdown file contains YAML frontmatter and structured sections:

--- title: "2:30:45 PM - May 31, 2025" date: 2025-05-31T14:30:45.123Z timestamp: 1717160645123 --- Reflections I'm excited about this new search feature... Technical Insights

Vector embeddings provide semantic understanding...

Development

Building

npm run build

Testing

npm test

Development Mode

npm run dev

Improving Claude's Performance

To help Claude learn and improve over time, consider adding journal usage guidance to your ~/.claude/CLAUDE.md file:

## Learning and Memory Management

- YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences - Before starting complex tasks, search the journal for relevant past experiences and lessons learned - Document architectural decisions and their outcomes for future reference - Track patterns in user feedback to improve collaboration over time - When you notice something that should be fixed but is unrelated to your current task, document it in your journal rather than fixing it immediately

This enables Claude to build persistent memory across conversations, leading to better engineering decisions and collaboration patterns.

Author

Jesse Vincent <jesse@fsck.com>

Read more about the motivation and design in the blog post.

License

MIT

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Private Journal MCP Server

Features

Journaling

Search & Discovery

Privacy & Performance

Installation

MCP Configuration

Claude Code (One-liner)

Manual Configuration

Configuration

PRIVATE_JOURNAL_PATH environment variable

--journal-path CLI argument

MCP Tools

process_thoughts

search_journal

read_journal_entry

list_recent_entries

File Structure

Project Journal (per project)

User Journal (global)

Entry Format

Reflections

Technical Insights

Development

Building

Testing

Development Mode

Improving Claude's Performance

Author

License

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`PRIVATE_JOURNAL_PATH` environment variable

`--journal-path` CLI argument

`process_thoughts`

`search_journal`

`read_journal_entry`

`list_recent_entries`