LogBook MCP

@cocaxcode/logbook-mcp

你的开发者日志簿，随时只需一句话。
笔记 · TODO · 提醒 · 代码扫描 · 全文搜索 · 原生 CLI · 仅支持 Obsidian

⚠️ v2.0 重大变更： 已移除 SQLite。v2 仅支持 Obsidian 后端。~/.logbook/logbook.db（v1）中的数据不会自动迁移，仍会原样保留在磁盘上。如果需要访问这些数据，请继续使用 @cocaxcode/[email protected]。工具数量从 10 个减少到 5 个（另有兼容垫片标记为已弃用）。详情请参阅 CHANGELOG.md。

概览 · 用法 · 安装 · 功能 · 工具参考 · 存储 · 架构

快速概览

logbook-mcp 是一个 MCP 服务，可将你的 AI 助手变成持久化的开发者日志簿。记录决策、跟踪 TODO、设置提醒、扫描代码中的 TODO，并通过全文搜索查找所有内容，无需离开编辑器。

它会自动检测你的 git 项目，在本地存储所有内容，并兼容任何支持 MCP 的客户端：Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codex CLI 或 Gemini CLI。所有数据都留在你的设备上——不会同步、不会跟踪，也不会离开你的磁盘。 笔记会自动按项目归类，但你也可以随时跨所有项目进行全局搜索。

两种存储模式：SQLite（默认，无需配置）或 Obsidian（带 frontmatter 的 Markdown 文件，可在你的 Obsidian 库中使用 Graph View、Dataview、Tasks 和 Calendar 查看）。从 SQLite 切换到 Obsidian 时，启动后会自动迁移数据。

直接告诉它

无需记忆命令，只需说出你的需求。

记录笔记

"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

跟踪 TODO

"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

设置提醒

"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

搜索任何内容

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

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

安装

Claude Code（推荐）

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

使用 Obsidian 模式：

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

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

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

使用 Obsidian 模式：

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

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

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

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

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

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

配置

logbook-mcp 支持三种存储配置方式，优先级如下：

1. CLI 参数（优先级最高）：--storage obsidian --dir "/path" --workspace "name"
2. 环境变量：LOGBOOK_STORAGE、LOGBOOK_DIR、LOGBOOK_WORKSPACE
3. 配置文件：~/.logbook/config.json（首次运行时自动创建）

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

从 SQLite 切换到 Obsidian

只需更改配置并重启。如果 autoMigrate 为 true（默认值），现有的 SQLite 数据会在下次启动时自动迁移到 Obsidian。无需手动操作。

也可以使用 logbook_setup action:status 查看当前状态。

功能

7 个内置主题

AI 会自动为每条笔记、TODO 和提醒分类，你也可以明确指定主题。

随时可以创建自定义主题——只需说 “创建一个名为 security 的主题”。

支持类型、文件夹和仪表板的自定义主题

主题可以定义自身的行为（kind）、Obsidian 文件夹，以及是否显示在项目仪表板（index.md）中：

• kind: note（默认）——每条记录都是一个独立的 .md 文件
• kind: todo ——记录会作为复选框写入一个汇总的 .md 文件
• show_in_index: true（默认）——在 index.md 中添加 Dataview 区块和快捷链接
• show_in_index: false ——主题仍然存在，但会在仪表板中隐藏

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

如果未设置 folder，记录会写入默认的 notes/ 或 todos/ 目录。创建 show_in_index: true 且设置了 folder 的主题时，会自动重新生成仪表板（index.md）。

扫描代码 TODO

通过 git grep 检测代码中的 TODO、FIXME、HACK 和 BUG 注释，并与手动添加的 TODO 一起显示：

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

当代码中的 TODO 从源代码中消失时（因为你已修复它），logbook 会自动检测并将其标记为已解决。

提醒

支持一次性和重复模式：

重复提醒每天显示一次后会自动确认。错过的一次性提醒会显示为逾期。

提示： logbook-mcp 提供了一个 MCP 资源（logbook://reminders），客户端可以在会话开始时加载。在 Claude Code 和 Claude Desktop 中，提醒会自动显示，无需询问。在其他客户端中，只需说 “有什么提醒吗？”。

全文搜索（FTS5）

由 SQLite FTS5 提供支持，可即时搜索所有笔记和 TODO。可按主题、类型、项目筛选，也可以跨所有项目全局搜索。

批量操作

"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

智能项目检测

logbook-mcp 通过 git rev-parse 自动检测你所在的 git 项目。无需配置——默认将查询范围限定为当前项目，也可以使用 global 选项查看所有内容。

工具参考

存储

SQLite 模式（默认）

所有数据都存储在 ~/.logbook/logbook.db 这一个 SQLite 数据库中。无需配置。

• WAL 模式支持并发读取
• FTS5 虚拟表支持即时全文搜索
• 触发器自动保持搜索索引同步
• 代码 TODO 快照——追踪现有的代码 TODO，并检测它们何时消失

Obsidian 模式

直接向 Obsidian 仓库写入带 YAML frontmatter 的 Markdown 文件。

通过 CLI 参数（推荐）、配置文件或环境变量进行配置：

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

文件按工作区、项目和类型组织：

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/

每个文件都带有 YAML frontmatter，Obsidian 插件可以对其进行查询：

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

推荐的 Obsidian 插件： Dataview（类似 SQL 的查询）、Calendar（日期视图）、Tasks（复选框管理）、Graph View（内置，可通过 [[wikilinks]] 显示关联）。

自动迁移： 从 SQLite 切换到 Obsidian 时，现有数据会在启动时自动迁移（如果 autoMigrate: true）。你也可以手动运行 logbook_setup action:migrate。

提示： 搭配 Self-hosted LiveSync 和 VPS 上的 CouchDB，即可在 PC、Android 和 iOS 设备之间免费同步你的仓库。

架构

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)

技术栈： TypeScript · MCP SDK · better-sqlite3 · Zod · tsup

MIT · 由 cocaxcode 构建