@cocaxcode/logbook-mcp

Your developer logbook, always one sentence away.
Notes · TODOs · Reminders · Code scanning · Full-text search · Zero config

Overview · Usage · Installation · Features · Tool Reference · Storage · Architecture

Quick Overview

logbook-mcp is an MCP server that turns your AI assistant into a persistent developer logbook. Capture decisions, track TODOs, set reminders, scan code TODOs, and search everything with full-text search — without leaving your editor.

It auto-detects your git project, stores everything in a local SQLite database at ~/.logbook/logbook.db, and works with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, or Gemini CLI. All data stays on your machine — nothing is synced, nothing is tracked, nothing leaves your disk. Notes are scoped per-project automatically, but you can search globally across all your projects at any time.

Just Talk to It

No commands to memorize. Just say what you need.

Capture notes

"I decided to use JWT instead of sessions for scalability"
→ Saved as a decision — retrievable months from now

"The CI is failing due to a timeout in integration tests"
→ Captured as a blocker — shows up when you review activity

Track TODOs

"TODO: implement email validation"
→ Created with auto-inferred topic

"Add these: fix token refresh. update deps. add rate limiting"
→ 3 TODOs created at once, each categorized

"Mark 5 and 8 as done"
→ Both completed

"What's pending across all projects?"
→ Global view of everything, including code TODOs

Set reminders

"Remind me tomorrow to deploy"
→ One-time reminder

"Remind me every Tuesday to review PRs"
→ Recurring weekly — auto-acknowledged after each session

"Remind me on weekdays to check the CI"
→ Monday to Friday

Search anything

"Why did we choose JWT?"
→ Finds the decision note, even months later

"Search everything about auth"
→ FTS5 search across all notes and TODOs

Installation

Claude Code (recommended)

claude mcp add --scope user logbook -- npx @cocaxcode/logbook-mcp@latest --mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

{
  "servers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

codex mcp add logbook-mcp -- npx @cocaxcode/logbook-mcp@latest --mcp

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": ["@cocaxcode/logbook-mcp@latest", "--mcp"]
    }
  }
}

Features

7 built-in topics

Every note, TODO, and reminder is categorized automatically by your AI, or you can specify a topic explicitly.

Custom topics can be created at any time — just say "create a topic called security".

Code TODO scanning

Your TODO, FIXME, HACK, and BUG comments are detected via git grep and shown alongside manual TODOs:

feature (2)
  [ ] #12 [manual] Implement email validation
      [code]  TODO: add OAuth support — src/auth/service.ts:45

fix (3)
  [ ] #8  [manual] Token doesn't refresh
      [code]  FIXME: handle null case — src/users/controller.ts:78
      [code]  BUG: race condition — src/chat/gateway.ts:112

When a code TODO disappears from source (because you fixed it), logbook detects it automatically and marks it as resolved.

Reminders

Both one-time and recurring patterns are supported:

Recurring reminders auto-acknowledge after being shown once per day. One-time reminders that were missed show as overdue.

Tip: logbook-mcp exposes an MCP Resource (logbook://reminders) that clients can load on session start. In Claude Code and Claude Desktop, reminders appear automatically without asking. In other clients, just say "any reminders?".

Full-text search (FTS5)

Search across all notes and TODOs instantly, powered by SQLite FTS5. Filter by topic, type, project, or search globally across all projects.

Batch operations

"Add: validate email. fix token. update deps"     → 3 TODOs created
"Mark 5, 8, and 12 as done"                       → 3 TODOs completed
"Delete TODOs 3 and 7"                             → 2 TODOs removed

Smart project detection

logbook-mcp auto-detects which git project you're in via git rev-parse. No config needed — it scopes queries to the current project by default, with a global option to see everything.

Tool Reference

Storage

All data lives in a single SQLite database at ~/.logbook/logbook.db.

~/.logbook/
└── logbook.db

• WAL mode for concurrent reads
• FTS5 virtual tables for instant full-text search
• Triggers keep search indexes in sync automatically
• Foreign keys with ON DELETE SET NULL — delete a project, notes remain
• Code TODO snapshots — tracks which code TODOs existed, detects when they disappear

Note: The database is created automatically on first use. No setup required.

Architecture

src/
├── index.ts              # Entry: --mcp → server, else CLI
├── server.ts             # createServer() — 9 tools + 1 resource
├── cli.ts                # CLI (help, version)
├── types.ts              # Shared interfaces
├── db/
│   ├── connection.ts     # getDb() singleton → ~/.logbook/logbook.db
│   ├── schema.ts         # Tables + FTS5 + triggers + topic seed
│   └── queries.ts        # Typed query functions + reminder logic
├── git/
│   ├── detect-repo.ts    # Auto-detect project via git rev-parse
│   └── code-todos.ts     # Scan TODO/FIXME/HACK/BUG via git grep
├── resources/
│   └── reminders.ts      # MCP Resource: logbook://reminders
└── tools/                # 9 MCP tools (one file each)

Stack: TypeScript · MCP SDK · better-sqlite3 · Zod · tsup

MIT · Built by cocaxcode