# korg-ledger

Logs what the agent did into a hash-chained ledger and lets you verify nothing was altered afterward. Useful when you need proof a session ran as recorded.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: New1Direction
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/New1Direction/korgex
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/mcp/korg-ledger

## What it does

The server exposes korgex tooling over MCP, so an agent can reach the session ledger and you can check its integrity later. A hash chain plus a causal graph tie events together, which is why a single changed character shows up during verification.

It runs through `uvx korgex`, so there is nothing to install separately. Set `KORG_JOURNAL_PATH` for the ledger file and `KORG_LEDGER_HMAC_KEY` for signing. Skip the key and authenticity checking has nothing to compare against.

Setup differs per platform. Claude and Codex take a `claude mcp add` or `codex mcp add` line with `--env` flags. Cursor and GitHub Copilot want a JSON block with `command`, `args` and `env`. Gemini CLI uses `gemini mcp add` with `-e`. Copy the whole block for your platform rather than retyping it.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `KORG_JOURNAL_PATH`, `KORG_LEDGER_HMAC_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> --env KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> --transport stdio korg-ledger -- uvx korgex
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>

### Codex

**Platform CLI**
```bash
codex mcp add korg-ledger --env KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> --env KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> -- uvx korgex
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "korg-ledger": {
            "command": "uvx",
            "args": [
                "korgex"
            ],
            "env": {
                "KORG_JOURNAL_PATH": "<KORG_JOURNAL_PATH>",
                "KORG_LEDGER_HMAC_KEY": "<KORG_LEDGER_HMAC_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "korg-ledger": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "korgex"
            ],
            "env": {
                "KORG_JOURNAL_PATH": "<KORG_JOURNAL_PATH>",
                "KORG_LEDGER_HMAC_KEY": "<KORG_LEDGER_HMAC_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> -e KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> korg-ledger uvx korgex
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>

## When to use it
- prove an agent session ledger was not edited after the run
- keep a signed record of agent actions for incident review
- wire the korgex ledger into an agent in Cursor or Claude
- point the ledger at your own directory with a signing key
- check session events against the hash chain and causal graph

## Example prompts
- Connect korg-ledger and show me what is in the current session ledger
- Verify the ledger: the hash chain and causal graph should match
- Set up korg-ledger with `KORG_JOURNAL_PATH` and `KORG_LEDGER_HMAC_KEY`

## Similar
- [Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres](https://affpapa.org/en/nevibecode/mcp/ekwo-os-open-source-accounting-ledger-invoices-and-vat-on-your-own-supabase-or-p.md) — MCP server · ★ 40
- [finance-expert](https://affpapa.org/en/nevibecode/skills/finance-expert.md) — skill · 6400 installs
- [continuity-ledger](https://affpapa.org/en/nevibecode/skills/continuity-ledger.md) — skill · 509 installs
- [Model Ledger](https://affpapa.org/en/nevibecode/mcp/model-ledger.md) — MCP server · ★ 17
- [agentic-ledger](https://affpapa.org/en/nevibecode/mcp/agentic-ledger.md) — MCP server · ★ 7
- [close-month](https://affpapa.org/en/nevibecode/skills/close-month.md) — skill · 1800 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md