dslh/journal-mcp

Journal-MCP

A simple tool for keeping a repository of journals.

What is a journal?

A journal is a YAML file that looks like this:

name: My Diary By Me
description: My super secret diary just for me. Keep out!
entries:
  - time: 2025-01-01T00:00:00Z
    text: >-
      # Today I ate an icecream

      It was strawberry flavoured and I really liked it.
  - time: 2025-01-02T12:34:56Z
    text: >-
      We went to the zoo today. I saw:
      - A tiger
      - Two monkeys
      - An elephant

      My friend Arthur came too and it was lots of fun.

What is a journal repository?

It's a git repository full of journal YAML files for tracking different topics. Subdirectories can be used to group journals by category.

journals/
├── kids/                    # Diaries for my children
|   ├── leo.yaml
|   ├── felix.yaml
|   └── ...
└-- projects/                # Progress reporting on various initiatives
    ├── journal-mcp.yaml
    ├── house-renovations.yaml
    └── ...

Any time an entry is added to a journal (or a new journal is added) it should be committed, and pushed to origin if it exists. By default the repo is kept in ~/.journals, but this can be changed with a JOURNAL_DIR environment variable.

What is Journal-MCP?

Journal-MCP is a command line tool that can be invoked directly by a user, or run as an MCP server. It has the following subcommands:

journal add

Adds an entry to the journal with the given name. For example kids/leo would refer to kids/leo.yaml.

• Creates a markdown file in the system's tmp directory
• Opens the file using $EDITOR
• Waits for the editor to exit
• Adds the contents of the temp file as a new entry in the named journal
• Deletes the temp file

Exits without action if the named journal does not exist or if the temp file is left blank.

journal new

Creates a new journal file.

• Creates any subdirectories in the journal name that don't already exist
• Creates a new yaml file for the journal, containing empty name: and description: fields
• Opens the file using $EDITOR
• Waits for the editor to exit

Deletes the file without committing if either name or description are left blank.

journal show [--since | --last ]

Prints entries from the named journal to stdout. Either the last n entries, or all entries since a given date, or all entries. Latest first. Does a bit of formatting:

2nd January 2025, 10:00 AM

# Today I ate an icecream

It was strawberry flavoured. I really liked it.

----------

1st January 2025, 12:34 PM

We went to the zoo today. I saw:
- A tiger
- Two monkeys
- An elephant

My friend Arthur came too and it was lots of fun.

journal list

Lists all of the journals in the journal repository.

Found 4 journal(s) in /Users/doug/.journals:

  kids/leo
    Name: Leo's Journal
    Description: The life and times of my eldest child
    Entries: 5 entries

  kids/felix
    Name: Felix's Journal
    Description: Like his brother, but smaller
    Entries: 6 entries

  ...

journal mcp [journal-name ...]

Starts as a stdio MCP server that exposes tools for viewing and appending to the named journals. When run without arguments, exposes all journals.

Exposes two tools per journal. Only the journal's file name is used for the tool name, subdirectories are not included. Tool description is derived from the journal name and description.

{
  "name": "add-to-journal-leo",
  "description": "Add an entry to Leo's Journal: A diary about my son",
  "inputSchema": {
    "type": "object",
    "properties": {
      "entry": { "type": "string", "description": "The contents of the journal entry, preferably using markdown format" }
    },
    "required": ["entry"]
  }
}

{
  "name": "read-journal-house-renovations",
  "description": "Read the latest entries from House Renovations: A weekly progress report",
  "inputSchema": {
    "type": "object",
    "properties": {
      "since": { "type": "string", "format": "date-time", "description": "List entries since this time" },
      "limit": { "type": "number", "description": "Maximum entries to return", "default": 10 }
    }
  }
}

Technical stuff

Language: Go
CLI Framework: github.com/urfave/cli/v2
MCP SDK: github.com/modelcontextprotocol/go-sdk
MCP Specification: 2025-06-18 (https://modelcontextprotocol.io/specification/2025-06-18)
Git Operations: go-git (github.com/go-git/go-git/v5) - pure Go implementation
Date Format: ISO 8601 for --since flag parsing
Error Handling: Detailed error messages for development/debugging

Build it: go build . Test it: go test ./... Contributing: You can