logbook MCP server

⚠️ v2.0 breaking change: SQLite eliminado. v2 sólo soporta backend Obsidian. Datos en ~/.logbook/logbook.db (v1) no se migran automáticamente — quedan intactos en disco. Si necesitas acceso a ellos, mantente en @cocaxcode/logbook-mcp@0.4. Tools 10→5 (con shims deprecated). Ver CHANGELOG.md para detalles.

---

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 locally, 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.

Two storage modes: SQLite (default, zero config) or Obsidian (markdown files with frontmatter, visible in your Obsidian vault with Graph View, Dataview, Tasks, and Calendar). Switching from SQLite to Obsidian auto-migrates your data on startup.

---

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 -y @cocaxcode/logbook-mcp@latest --mcp

With Obsidian mode:

claude mcp add --scope user logbook -- npx -y @cocaxcode/logbook-mcp@latest --mcp --storage obsidian --dir "/path/to/vault/logbook"

Claude Desktop

Add to your claude_desktop_config.json:

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

With Obsidian mode:

{
  "mcpServers": {
    "logbook-mcp": {
      "command": "npx",
      "args": [
        "-y", "@cocaxcode/logbook-mcp@latest", "--mcp",
        "--storage", "obsidian",
        "--dir", "/path/to/vault/logbook"
      ]
    }
  }
}

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor — add to .cursor/mcp.json:

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

Windsurf — add to .windsurf/mcp.json:

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

VS Code — add to .vscode/mcp.json:

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

Codex CLI:

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

Gemini CLI — add to .gemini/settings.json:

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

---

Configuration

logbook-mcp supports three ways to configure storage, with this priority order:

1. CLI args (highest priority): --storage obsidian --dir "/path" --workspace "name"
2. Environment variables: LOGBOOK_STORAGE, LOGBOOK_DIR, LOGBOOK_WORKSPACE
3. Config file: ~/.logbook/config.json (auto-created on first run)

{
  "storage": "sqlite",
  "dir": null,
  "workspace": null,
  "autoMigrate": true
}

Switching from SQLite to Obsidian

Just change the config and restart. If autoMigrate is true (default), your existing SQLite data is automatically migrated to Obsidian on the next startup. No manual steps needed.

You can also check the current status with logbook_setup action:status.

---

Features

7 built-in topics

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

Topic	Purpose	Mapped from conventional commits
feature	New functionality	feat:
fix	Bug fixes	fix:
chore	Maintenance, CI/CD, refactoring	refactor: docs: ci: build: test:
idea	Future proposals	—
decision	Architecture choices	—
blocker	Things blocking progress	—
reminder	Time-based reminders	—

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

Custom topics with type, folder, and dashboard

Topics can define their own behavior (kind), Obsidian folder, and whether they appear in the project dashboard (index.md):

• kind: note (default) — each entry is an individual .md file
• kind: todo — entries are checkboxes in a consolidated .md file
• show_in_index: true (default) — adds a Dataview section and quick link to index.md
• show_in_index: false — topic exists but is hidden from the dashboard

"Create a topic called incident with its own folder"
→ logbook_topics action:add name:"incident" kind:"note" folder:"incidents"
→ Entries saved to: project/incidents/2026-03-24-server-down.md
→ Dashboard updated with Incidents section

"Create a topic called sprint-task as todo type"
→ logbook_topics action:add name:"sprint-task" kind:"todo" folder:"sprint"
→ Entries saved to: project/sprint.md (as checkboxes)

"Create a private topic not shown in the dashboard"
→ logbook_topics action:add name:"internal" kind:"note" folder:"internal" show_in_index:false
→ Entries saved to: project/internal/ (not visible in index.md)

Without a folder, entries go to the default notes/ or todos/ directory. The dashboard (index.md) is auto-regenerated when a topic with show_in_index: true and folder is created.

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:

Pattern	Example	Schedule
One-time	remind_at: "2026-03-25"	March 25 only
daily	Every day	Every day
weekdays	Monday to Friday	Mon–Fri
weekly:2	Every Tuesday	Specific day of week
weekly:1,3	Monday and Wednesday	Multiple days
monthly:1	1st of each month	Specific day of month
monthly:1,15	1st and 15th	Multiple days

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

Tool	Actions	Description
logbook_note	—	Add a note with optional topic
logbook_todo	add list done edit rm	Full TODO management
logbook_entry	list edit delete standup decision debug	Structured entries (ADRs, debug sessions, standups)
logbook_query	search log timeline	Full-text search, activity log, cross-project timeline
logbook_topics	list add	Manage topics (custom kind, folder, dashboard visibility)
logbook_tags	—	List tags with counts
logbook_reminders	—	View pending reminders
logbook_review	—	Weekly/monthly review with stats
logbook_inbox	list process	Quick notes inbox (Obsidian mode)
logbook_setup	init migrate status	Admin: init vault, migrate data, check status
		10 tools + 1 resource

Param	Type	Required	Description
content	string	Yes	Note content (max 5000 chars)
topic	string	No	Topic name — AI infers it, or auto-created if new

action: add — Create TODOs

Param	Type	Description
content	string	Single TODO content (max 2000 chars)
items	array	Multiple TODOs: [{content, topic?, priority?, remind_at?, remind_pattern?}] (max 50)
topic	string	Topic — auto-inferred or auto-created
priority	low normal high urgent	Priority (default: normal)
remind_at	YYYY-MM-DD	One-time reminder date
remind_pattern	string	Recurring: daily, weekdays, weekly:N, monthly:N

action: list — List TODOs grouped by topic

Param	Type	Default	Description
status	pending done all	pending	Filter by status
topic	string	—	Filter by topic
priority	low normal high urgent	—	Filter by priority
source	all manual code	all	Manual DB or code comments
scope	project global	project	Current project or all

action: done — Mark as done / undo

Param	Type	Description
ids	number or number[]	ID(s) to mark
undo	boolean	If true, sets back to pending (default: false)

action: edit — Edit a TODO

Param	Type	Description
id	number	TODO ID to edit
content	string	New content
topic	string	New topic
priority	low normal high urgent	New priority

action: rm — Delete TODOs

Param	Type	Description
ids	number or number[]	ID(s) to delete permanently

action: standup — Daily standup

Param	Type	Required	Description
yesterday	string	Yes	What was done yesterday
today	string	Yes	What will be done today
blockers	string	No	Current blockers
topic	string	No	Topic

action: decision — Architecture Decision Record (ADR)

Param	Type	Required	Description
title	string	Yes	Decision title
context	string	Yes	Why this decision is needed
options	string[]	Yes	Options considered
decision	string	Yes	Decision taken
consequences	string	Yes	Consequences of the decision
topic	string	No	Topic (default: decision)

action: debug — Debug session

Param	Type	Required	Description
title	string	Yes	Bug/error title
error	string	Yes	Error description
cause	string	Yes	Root cause
fix	string	Yes	Solution applied
file	string	No	Attachment path
topic	string	No	Topic (default: fix)

action: list — List entries by type

Param	Type	Default	Description
type	note decision debug standup review	—	Entry type (required)
scope	project global	project	Current project or all
limit	number	20	Max results

action: edit / action: delete — Modify or remove entries by ID

action: search — Full-text search

Param	Type	Default	Description
query	string	—	Search text (required)
type	all notes todos	all	Search scope
topic	string	—	Filter by topic
scope	project global	project	Project or global
limit	number	20	Max results

action: log — Activity for a period

Param	Type	Default	Description
period	today yesterday week month	today	Quick date filter
from / to	YYYY-MM-DD	—	Custom date range
type	all notes todos	all	Filter by type
scope	project global	project	Current project or all

action: timeline — Cross-project timeline

Param	Type	Default	Description
period	today yesterday week month	week	Time range
workspace	string	—	Filter by workspace

action: status — Show current configuration and migration state

action: init — Initialize Obsidian vault (dashboard, templates, inbox)

Param	Type	Default	Description
force	boolean	false	Regenerate even if files exist

action: migrate — Manually migrate SQLite data to Obsidian (requires obsidian mode)

---

Storage

SQLite mode (default)

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

• WAL mode for concurrent reads
• FTS5 virtual tables for instant full-text search
• Triggers keep search indexes in sync automatically
• Code TODO snapshots — tracks which code TODOs existed, detects when they disappear

Obsidian mode

Writes markdown files with YAML frontmatter directly to your Obsidian vault.

Configure via CLI args (recommended), config file, or env vars:

# CLI args (most reliable, especially on Windows)
claude mcp add logbook -- npx -y @cocaxcode/logbook-mcp@latest --mcp --storage obsidian --dir "/path/to/vault/logbook"

// Config file: ~/.logbook/config.json
{
  "storage": "obsidian",
  "dir": "/path/to/vault/logbook",
  "autoMigrate": true
}

Files are organized by workspace, project, and type:

vault/logbook/
├── cocaxcode/
│   ├── cocaxcode-api/
│   │   ├── notes/          ← logbook_note
│   │   ├── todos/          ← logbook_todo
│   │   ├── decisions/      ← logbook_entry action:decision
│   │   ├── debug/          ← logbook_entry action:debug
│   │   ├── standups/       ← logbook_entry action:standup
│   │   └── attachments/    ← copied files
│   └── cocaxcode-web/
├── optimus/
│   └── optimus-hub/

Each file has YAML frontmatter that Obsidian plugins can query:

---
type: todo
date: 2026-03-21
project: cocaxcode-api
workspace: cocaxcode
status: pending
priority: high
due: 2026-03-25
tags: [auth, urgent]
---
- [ ] Fix JWT refresh token

Recommended Obsidian plugins: Dataview (SQL-like queries), Calendar (date view), Tasks (checkbox management), Graph View (built-in, shows connections via [[wikilinks]]).

Auto-migration: When switching from SQLite to Obsidian, existing data is migrated automatically on startup (if autoMigrate: true). You can also run logbook_setup action:migrate manually.

Tip: Combine with Self-hosted LiveSync + CouchDB on your VPS to sync your vault across PC, Android, and iOS for free.

---

Architecture

src/
├── index.ts              # Entry: --mcp → server, else CLI
├── server.ts             # createServer() — 10 tools + 1 resource
├── config.ts             # Config resolution (args > env > file > defaults)
├── auto-migrate.ts       # Auto SQLite → Obsidian migration on startup
├── cli.ts                # CLI (help, version)
├── types.ts              # Shared interfaces
├── storage/
│   ├── types.ts          # StorageBackend interface
│   ├── index.ts          # getStorage() factory (uses resolveConfig)
│   ├── sqlite/           # SQLite backend (wraps db/)
│   └── obsidian/         # Obsidian backend (markdown + frontmatter)
├── db/                   # SQLite internals
├── git/                  # Git repo detection + code TODO scanning
├── resources/            # MCP Resource: logbook://reminders
└── tools/                # 10 MCP tools (one file each)

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

---

MIT · Built by cocaxcode