Skip to main content
Glama
journalowl-mcp

journalowl-mcp

by mindfullabai
README.md
# @mindfulabai/journalowl-mcp

MCP (Model Context Protocol) server for [JournalOwl](https://journalowl.com) - AI-powered journaling integration for Claude Code, Cursor, and ChatGPT Agents.

## Features

- **Create journal entries** directly from your AI assistant
- **Search and browse** your journal entries
- **Access weekly reviews** with emotional trends and insights
- **Get personalized suggestions** based on your writing style
- **Secure API key authentication** with scoped permissions

## Installation

```bash
npx @mindfulabai/journalowl-mcp
```

Or install globally:

```bash
npm install -g @mindfulabai/journalowl-mcp
```

## Configuration

### 1. Get your API Key

1. Log in to [JournalOwl](https://journalowl.com)
2. Go to **Settings > API Keys**
3. Create a new API key with the scopes you need:
   - `journal:read` - Read your journal entries
   - `journal:write` - Create new entries
   - `review:read` - Access weekly reviews
   - `profile:read` - Access your profile and writing style

### 2. Configure Claude Code

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "journalowl": {
      "command": "npx",
      "args": ["@mindfulabai/journalowl-mcp"],
      "env": {
        "JOURNALOWL_API_KEY": "jowl_sk_your_api_key_here"
      }
    }
  }
}
```

### 3. Configure Cursor

Add to your Cursor MCP settings:

```json
{
  "journalowl": {
    "command": "npx",
    "args": ["@mindfulabai/journalowl-mcp"],
    "env": {
      "JOURNALOWL_API_KEY": "jowl_sk_your_api_key_here"
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `journal_create_entry` | Create a new journal entry |
| `journal_list_entries` | List entries with filters |
| `journal_get_entry` | Get entry details and analysis |
| `journal_search` | Search entries by text |
| `journal_get_weekly_review` | Get weekly review and insights |
| `journal_get_writing_style` | Get writing style preferences |

## Available Resources

| URI | Description |
|-----|-------------|
| `journalowl://user/profile` | User profile and journaling stats |
| `journalowl://user/recent-entries` | Recent entries metadata |

## Example Usage

Once configured, you can use JournalOwl directly in your AI conversations:

```
"Create a journal entry about my productive day at work"

"Show me my journal entries from last week"

"What insights does my weekly review show?"

"Search my journal for entries about anxiety"
```

## Development

```bash
# Clone the repository
git clone https://github.com/mindfulabai/journalowl-mcp.git
cd journalowl-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Test with MCP Inspector
npm run inspector
```

## Security

- API keys are transmitted securely via HTTPS
- Keys are hashed in our database (we never store the plain key)
- You can revoke keys at any time from JournalOwl settings
- Scopes limit what each key can access

## Support

- [Documentation](https://docs.journalowl.com/mcp)
- [GitHub Issues](https://github.com/mindfulabai/journalowl-mcp/issues)
- [JournalOwl Support](https://journalowl.com/support)

## License

MIT

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

Each tool targets a distinct action, but journal_list_entries and journal_search both retrieve entries with different filter types (metadata vs text), which could cause minor confusion. Overall the purposes are clear.

Naming Consistency4/5

All tools share the journal_ prefix and use snake_case, but journal_search is verb-only while others follow verb_noun (e.g., journal_get_entry), creating a slight inconsistency.

Tool Count5/5

Seven tools is well-scoped for a journaling server, covering creation, retrieval, search, and analysis without unnecessary redundancy or bloat.

Completeness3/5

The create-read workflow is well-covered (create, finalize, list, get, search), but there are no update or delete tools for entries, and no way to modify writing style preferences, creating notable lifecycle gaps.