io.github.cocaxcode/logbook-mcp

Developer logbook MCP server. Notes, TODOs, standups, decisions, debug sessions, reminders.
Open source Open in the app JSON README (API)
About

Developer logbook MCP server. Notes, TODOs, standups, decisions, debug sessions, reminders.
Details

Kind: MCP servers
Topic: No topic detected
Publisher: cocaxcode
Origin: official
Category: ferramentas
Transport: local
Version: 0.8.11
Stars: 1
Last push: 2026-05-06T22:43:14Z
Repository state: ativo
Language: TypeScript
License: MIT
Added: 2026-08-29 03:02:36
Updated: 2026-08-29 03:02:36
Origin id: io.github.cocaxcode/logbook-mcp
README

<p align="center">
  <h1 align="center">@cocaxcode/logbook-mcp</h1>
  <p align="center">
    <strong>Your developer logbook, always one sentence away.</strong><br/>
    Notes &middot; TODOs &middot; Reminders &middot; Code scanning &middot; Full-text search &middot; Native CLI &middot; Obsidian-only
  </p>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@cocaxcode/logbook-mcp"><img src="https://img.shields.io/npm/v/@cocaxcode/logbook-mcp.svg?style=flat-square&color=cb3837" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@cocaxcode/logbook-mcp"><img src="https://img.shields.io/npm/dm/@cocaxcode/logbook-mcp.svg?style=flat-square" alt="npm downloads" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node" />
  <img src="https://img.shields.io/badge/tools-5%20%2B%205%20deprecated-blueviolet?style=flat-square" alt="5 + 5 deprecated" />
</p>

> **⚠️ 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](./CHANGELOG.md) para detalles.

<p align="center">
  <a href="#quick-overview">Overview</a> &middot;
  <a href="#just-talk-to-it">Usage</a> &middot;
  <a href="#installation">Installation</a> &middot;
  <a href="#features">Features</a> &middot;
  <a href="#tool-reference">Tool Reference</a> &middot;
  <a href="#storage">Storage</a> &middot;
  <a href="#architecture">Architecture</a>
</p>

---

## 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)

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

With Obsidian mode:

```bash
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`:

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

With Obsidian mode:

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

<details>
<summary>Config file locations</summary>

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
</details>

<details>
<summary>Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI</summary>

**Cursor** — add to `.cursor/mcp.json`:

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

**Windsurf** — add to `.windsurf/mcp.json`:

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

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

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

**Codex CLI**:

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

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

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

</details>

---

## 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)

```json
{
  "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** |

<details>
<summary><code>logbook_note</code> — Add a note</summary>

| 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 |
</details>

<details>
<summary><code>logbook_todo</code> — Full TODO management</summary>

**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 |
</details>

<details>
<summary><code>logbook_entry</code> — Structured entries</summary>

**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
</details>

<details>
<summary><code>logbook_query</code> — Search and activity</summary>

**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 |
</details>

<details>
<summary><code>logbook_setup</code> — Admin tools</summary>

**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)
</details>

---

## 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:

```bash
# 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"
```

```json
// 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:

```yaml
---
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](https://github.com/vrtmrz/obsidian-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 &middot; MCP SDK &middot; better-sqlite3 &middot; Zod &middot; tsup

---

[MIT](./LICENSE) &middot; Built by [cocaxcode](https://github.com/cocaxcode)
io.github.cocaxcode/logbook-mcp

About

Details

README

More
