konbu

<p align="center"> <img src="web/static/favicon.svg" width="64" height="64" alt="konbu"> </p>

<h1 align="center">konbu</h1>

<p align="center"> <strong>Your personal digital planner, kept by an AI butler.</strong><br> CLI · MCP · Self-hostable · AI-native </p>

<p align="center"> One Go binary that binds your memos, todos, schedule, and tables into a single planner — searchable from one place, kept by AI.<br> Connect Claude, Cursor, or any MCP client to your data. </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a> <a href="https://github.com/krtw00/konbu/actions"><img src="https://github.com/krtw00/konbu/actions/workflows/deploy.yml/badge.svg" alt="Deploy"></a> </p>

<p align="center"><a href="README.ja.md">日本語</a> | English</p>

<p align="center"><img src="docs/screenshot.png" width="800" alt="konbu screenshot"></p>

<p align="center"><img src="docs/demo.gif" width="800" alt="AI chat demo — managing schedule and todos with natural language"></p>

---

Try It

• Cloud -- Use instantly at konbu-cloud.codenica.dev (free, no setup)
• Self-hosted -- Run on your own server with Docker (see below)

What is konbu?

konbu is a personal digital planner — a Filofax-style system planner, digitized. A self-hostable Go binary that binds your memos, todos, schedule, and structured tables into one notebook, kept by an AI butler, and surfaces everything from a single search interface. It's yours alone — nothing is ever shared out. Not a replacement for Notion + Todoist + Calendar — a replacement for the act of searching four apps to find one thing.

What's different:

• Native MCP server + CLI client -- Two parallel routes for the AI butler (Claude / Cursor / any MCP client) or shell / scripts to operate your planner.
• Cross-resource full-text search -- One query across memos, todos, events, and structured tables. This is the core UX, not a side feature.
• Structured tables (= table-memo, planned) -- Track blood pressure, household budgets, or inventory. Markdown can't express these; tables can.
• BYOK AI chat -- Bring your own OpenAI/Anthropic API key, or use the included free tier.
• Personal by design -- One notebook, for you only. Pulls in from outside (Google Calendar), never leaks out.
• Self-hostable -- One Go binary, Docker compose, or use the hosted version.

End the state of having your day scattered across four different apps.

Features

• Cross-resource Full-text Search -- Search across memos, todos, events, and structured tables in one query (core UX)
• CLI & MCP Server -- Built-in CLI client and MCP server. AI agents like Claude and Cursor can read and write your data directly
• AI Agent Chat -- "Add groceries to my todo" "What's on my schedule tomorrow?" in natural language. BYOK supported, free tier included
• Memos -- Markdown notes with tagging, live preview
• ToDo -- Inline task creation with due dates, tags, and notes
• Calendar -- Monthly view with event CRUD and iCal import (personal, owner-only)
• Structured Tables (= table-memo, planned) -- Track structured data (blood pressure, household budget, inventory) as rows × columns
• Export/Import -- JSON export, Markdown ZIP export, iCal import
• i18n -- English and Japanese

Quick Start

cp .env.example .env
docker compose up -d

Open http://localhost:8080 and create your account. The dev compose file sets DEV_USER=dev@local to skip registration.

Production (with Traefik)

# Edit .env with real credentials and your domain
docker compose -f docker-compose.prod.yml up -d

Native (without Docker)

# Prerequisites: Go 1.25+, Node.js 22+, PostgreSQL 16+

# Build frontend
cd web/frontend && npm ci && npm run build && cd ../..

# Build server
go build -o bin/server ./cmd/server

# Start (runs all SQL migrations automatically on boot)
DATABASE_URL="postgres://..." SESSION_SECRET="..." ./bin/server

Configuration

Variable	Required	Default	Description
DATABASE_URL	Yes	--	PostgreSQL connection string
SESSION_SECRET	Yes	dev fallback	Session signing key
PORT	No	8080	Server port
DEV_USER	No	--	Auto-login as this email (dev only)
OPEN_REGISTRATION	No	--	Set true to allow anyone to register (for Cloud)
BASE_URL	No	--	Public app URL used for OAuth callbacks
GOOGLE_CLIENT_ID	No	--	Enable Google OAuth login
GOOGLE_CLIENT_SECRET	No	--	Enable Google OAuth login
WEBHOOK_SECRET	No	--	GitHub Sponsors webhook secret
STRIPE_SECRET_KEY	No	--	Enable Stripe checkout and subscription billing
STRIPE_WEBHOOK_SECRET	No	--	Verify incoming Stripe webhook events
STRIPE_PRICE_MONTHLY	No	--	Stripe Price ID used for monthly Pro checkout
STRIPE_PRICE_YEARLY	No	--	Stripe Price ID used for yearly Pro checkout
GITHUB_FEEDBACK_TOKEN	No	--	GitHub token used to create anonymized feedback issues
GITHUB_FEEDBACK_REPO	No	--	Repository to receive feedback issues, e.g. krtw00/konbu
GITHUB_FEEDBACK_LABELS	No	--	Comma-separated labels added to forwarded feedback issues
AI_ENCRYPTION_KEY	No	--	64 hex chars used to encrypt BYOK AI keys
DEFAULT_AI_PROVIDER	No	openai	Server-side free-tier AI provider
DEFAULT_AI_API_KEY	No	--	Server-side free-tier AI key
DEFAULT_AI_ENDPOINT	No	--	Override free-tier provider endpoint
DEFAULT_AI_MODEL	No	--	Override free-tier provider model
R2_ACCESS_KEY_ID	No	--	Attachment upload credentials
R2_SECRET_ACCESS_KEY	No	--	Attachment upload credentials
R2_ENDPOINT	No	Cloudflare R2 default	Attachment storage endpoint
R2_BUCKET	No	konbu-attachments	Attachment storage bucket
R2_PUBLIC_URL	No	--	Optional public base URL for attachments
SMTP_HOST	No	--	SMTP relay host for reminder emails (e.g. smtp-relay.brevo.com). Notifications are disabled unless all five SMTP_* variables are set.
SMTP_PORT	No	--	SMTP relay port (typically 587 for STARTTLS)
SMTP_USERNAME	No	--	SMTP relay login
SMTP_PASSWORD	No	--	SMTP relay password / API key
SMTP_FROM	No	--	From address for outgoing reminder emails
NOTIFICATION_TICK_INTERVAL	No	1m	Notification sweep interval (Go duration, e.g. 30s, 2m)

Reminders / notifications

When the SMTP_* variables above are all set, the server starts a single in-process sweep loop that sends email reminders for upcoming events and due ToDos. Each user opts in via Settings (user_settings.notifications.enabled = true) and can override the recipient email, lead time, due-time, and timezone.

Notifications are a server-only feature — they run inside the API server process and require PostgreSQL. The MCP --standalone mode (SQLite) does not send reminders.

Docker Compose (prod) variables

Variable	Description
POSTGRES_PASSWORD	PostgreSQL password
KONBU_DOMAIN	Domain for Traefik TLS routing

CLI

The CLI is a standalone client that connects to a remote konbu server via API. Server code is not included in the CLI binary.

go install github.com/krtw00/konbu/cmd/konbu@latest

Setup

# Set environment variables (recommended: add to ~/.zshrc or ~/.bashrc)
export KONBU_API=https://konbu.example.com
export KONBU_API_KEY=your-api-key

# Or pass as flags
konbu --api https://... --api-key your-key memo list

Generate an API key in Settings > Security on the web UI.

Commands

All commands support --json flag for machine-readable output.

konbu memo list                        # List memos
konbu memo show <id>                   # Show memo content
konbu memo add "title" -c "content"    # Create memo (-c - for stdin)
konbu memo edit <id> --title "new"     # Update memo
konbu memo rm <id>                     # Delete memo

konbu todo list                        # List todos
konbu todo show <id>                   # Show todo details
konbu todo add "task" -t "tag1,tag2"   # Create todo
konbu todo add "task" -d 2025-04-01    # Create with due date
konbu todo edit <id> --desc "notes"    # Update todo
konbu todo done <id>                   # Mark done
konbu todo reopen <id>                 # Reopen
konbu todo rm <id>                     # Delete

konbu event list                       # List events
konbu event show <id>                  # Show event details
konbu event add "title" -s <RFC3339>   # Create event
konbu event edit <id> --title "new"    # Update event
konbu event rm <id>                    # Delete

konbu tag list                         # List tags
konbu tag rm <id>                      # Delete tag

konbu search "query"                   # Cross-search

konbu api-key list                     # List API keys
konbu api-key create "key-name"        # Create API key
konbu api-key rm <id>                  # Delete API key

konbu export json -o backup.json       # Export as JSON
konbu export markdown -o backup.zip    # Export as Markdown ZIP
konbu import ical calendar.ics         # Import iCal file

Short IDs (first 8 chars) can be used in place of full UUIDs.

MCP Server

konbu can run as a built-in MCP (Model Context Protocol) server in two modes — pick whichever fits.

Standalone mode (SQLite, no server required)

If you just want konbu as a local MCP backend for Claude Desktop, Cursor, or any MCP client, install the CLI and run it with --standalone. No PostgreSQL, no web server, no API key — everything is stored in a local SQLite file.

go install github.com/krtw00/konbu/cmd/konbu@latest
konbu mcp --standalone

Data is persisted at ~/.konbu/konbu.db by default. Override with --db /path/to/db.sqlite if needed.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "konbu": {
      "command": "konbu",
      "args": ["mcp", "--standalone"]
    }
  }
}

Cursor accepts the same config at ~/.cursor/mcp.json (or via the settings UI).

Docker

A multi-arch image (linux/amd64, linux/arm64) is published to GitHub Container Registry. Pull it directly — no build step needed:

docker pull ghcr.io/krtw00/konbu-mcp:latest

For reproducible setups, pin to a release tag instead — e.g. docker pull ghcr.io/krtw00/konbu-mcp:v0.2.0.

Then point your MCP client at it. Data persists in a named volume:

{
  "mcpServers": {
    "konbu": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "konbu-data:/data", "ghcr.io/krtw00/konbu-mcp:latest"]
    }
  }
}

Prefer building from source? docker build -f docker/Dockerfile.mcp -t konbu-mcp . from the repo root produces the same image (CGO-free, distroless static, ~22 MB).

Standalone mode exposes memo / todo / calendar event CRUD plus cross-resource search. Tags, attachments, and AI chat are server-only (use the connected mode below for those).

Connected mode (talk to a konbu server)

If you're running a konbu server (self-hosted or konbu Cloud), point the MCP server at it over HTTP. You get the full feature set: tags, attachments, and AI chat.

1. Install the konbu CLI binary (see CLI section above)
2. Generate an API key in Settings > Security on the web UI
3. Add konbu to your MCP client config:

{
  "mcpServers": {
    "konbu": {
      "command": "konbu",
      "args": ["mcp"],
      "env": {
        "KONBU_API": "http://localhost:8080",
        "KONBU_API_KEY": "your-api-key"
      }
    }
  }
}

Usage examples

After restarting your MCP client, interact with konbu in natural language:

• "What's on my schedule tomorrow?"
• "Add a dentist appointment next Friday at 1pm"
• "Create a todo to buy groceries with tag 'shopping'"
• "Show me notes tagged 'meeting' from last week"
• "Mark the 'review PR' todo as done"

API

Base path: /api/v1

Resource	Endpoints
Auth	POST /auth/register, POST /auth/login, POST /auth/logout, GET /auth/setup-status, GET /auth/providers, GET /auth/google/login, GET /auth/google/callback
User	GET/PUT /auth/me, GET/PUT /auth/settings, POST /auth/change-password, POST /auth/delete-account
API Keys	GET/POST /api-keys, DELETE /api-keys/:id
Memos	GET/POST /memos, GET/PUT/DELETE /memos/:id, GET/POST /memos/:id/rows, POST /memos/:id/rows/batch, GET /memos/:id/rows/export, PUT/DELETE /memos/:id/rows/:rowId
ToDos	GET/POST /todos, GET/PUT/DELETE /todos/:id, PATCH /todos/:id/done, PATCH /todos/:id/reopen
Events	GET/POST /events, GET/PUT/DELETE /events/:id
Calendars	GET/POST /calendars, GET/PUT/DELETE /calendars/:id (owner-only)
Tags	GET/POST /tags, PUT/DELETE /tags/:id
Search	GET /search?q=...
Chat	GET/POST /chat/sessions, GET/PUT/DELETE /chat/sessions/:id, POST /chat/sessions/:id/messages, GET/PUT /chat/config
Attachments	POST /attachments, GET /attachments/*
Export	GET /export/json, GET /export/markdown
Import	POST /import/ical

Development

# Start PostgreSQL
docker compose up -d postgres

# Frontend dev server
cd web/frontend && npm run dev

# Run server
DEV_USER=dev@local go run ./cmd/server

# Build CLI
go build -o bin/konbu ./cmd/konbu

# Run tests
go test ./...
cd web/frontend && npm test
cd web/frontend && npm run test:e2e

Project Structure

cmd/
  server/       # API server
  konbu/        # CLI client
internal/
  handler/      # HTTP handlers
  service/      # Business logic
  repository/   # DB access (sqlc)
  middleware/   # Auth, logging
  client/       # API client (used by CLI)
  mcp/          # MCP server
web/frontend/   # React + Vite SPA
sql/            # Schema and migrations
docker/         # Dockerfile

Roadmap

• Browser push reminders (email reminders are already supported when SMTP_* env is configured)
• Mobile UI improvements
• CI test coverage
• AI chat enhancements (context improvements, new model support)

Sponsors

If you find konbu useful, consider sponsoring the project.

License

MIT