Journal

A Model Context Protocol (MCP) server for journal entries with a React Router v7 web viewer.

Features

• 📖 MCP Server: Integration with Claude Desktop for journal management
• 🌐 Web Viewer: React-based interface for browsing journal entries
• 🚀 Server-side rendering with React Router
• ⚡️ Hot Module Replacement (HMR) for development
• 🔒 TypeScript by default
• 🎉 TailwindCSS for styling
• 📁 File-based storage with automatic organization

Getting Started

Quick Start with npx

Run directly without installation:

# Start web viewer
npx @coji/journal-mcp --viewer

# Setup Claude Desktop integration
npx @coji/journal-mcp --setup

# Start MCP server for Claude Desktop
npx @coji/journal-mcp

Local Development

Install the dependencies:

pnpm install

Development

Start the development server with HMR:

pnpm dev

Your web viewer will be available at http://localhost:5173.

Building for Production

Create a production build:

pnpm build

Usage

Using npx (Recommended)

# Show help
npx @coji/journal-mcp --help

# Setup Claude Desktop integration
npx @coji/journal-mcp --setup

# Verify Claude Desktop setup
npx @coji/journal-mcp --verify-setup

# Start MCP server for Claude Desktop
npx @coji/journal-mcp

# Start web viewer
npx @coji/journal-mcp --viewer

# Custom port examples
npx @coji/journal-mcp --viewer --port 8080

Local Development Commands

For development after local installation:

# Show help
node dist/index.js --help

# Setup Claude Desktop configuration
node dist/index.js --setup

# Start MCP server
node dist/index.js

# Start web viewer
node dist/index.js --viewer

The web viewer will be available at http://localhost:8765 (or your specified port).

MCP Tools

The server provides these tools for Claude Desktop:

1. add_entry - Add new journal entries
2. search_entries - Search by date range, tags, or keywords
3. get_recent_entries - Get most recent entries
4. list_tags - List all tags with usage counts
5. get_entry_by_date - Get entries for a specific date
6. get_daily_summary - Get journal statistics

File Storage

Journal entries are stored in:

• Location: ~/.local/share/journal-mcp/entries/YYYY/MM/YYYY-MM-DD.md
• Format: Markdown with YAML frontmatter
• Features: Automatic tag extraction, time-based organization

Deployment

Docker Deployment

docker build -t journal-mcp .
docker run -p 8765:8765 journal-mcp

Manual Deployment

Deploy the output of pnpm build:

├── package.json
├── pnpm-lock.yaml
├── build/
│   ├── client/    # Static assets
│   └── server/    # Server-side code

---

Built with ❤️ using React Router and MCP.