Skip to main content
Glama
kty1965

akiflow-toolkit

by kty1965
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

akiflow-toolkit

Unofficial project. Not affiliated with Akiflow Inc. Uses reverse-engineered internal API. May break without notice. See DISCLAIMER.md.

Unofficial CLI and MCP server for Akiflow, enabling terminal-based task management and AI agent integration (Claude Code, Cursor, Claude Desktop).

Status

Alpha — Published to npm as akiflow-toolkit. Requires Bun 1.1+ runtime.

Related MCP server: MCP Todoist

Planned Features

  • CLI (af): Task management from terminal — add, list, complete, schedule, projects, calendar

  • MCP Server (af --mcp): AI agent integration via Model Context Protocol

  • Auto Authentication: Extracts tokens from browser data (IndexedDB, cookies) — no manual DevTools copy

  • Token Auto-Recovery: 3-tier recovery when tokens expire (refresh → disk reload → browser re-extract)

  • Cross-browser: Chrome, Arc, Brave, Edge, Safari support (macOS)

Architecture

Key decisions are documented as Architecture Decision Records (ADRs):

  • ADR Index — All 15 ADRs

  • Highlights: Bun runtime, Hexagonal (Ports & Adapters), Outcome-first MCP Tools, semantic-release, Test Diamond

Runtime Requirement — Bun Only

akiflow-toolkit은 Bun runtime 전용 CLI입니다. Node.js로는 실행할 수 없습니다.

  • 배포 번들이 bun:sqlite 등 Bun 네이티브 모듈을 직접 사용합니다 (Chrome cookie DB 파싱 용도).

  • shebang이 #!/usr/bin/env bun으로 고정되어 있습니다.

  • Bun은 Node.js 호환 API를 대부분 지원하므로 기능적 제약은 거의 없습니다.

Node.js 지원이 필요하면 better-sqlite3로 교체하는 별도 마이그레이션이 필요합니다 (docs/tasks/ 참고).

Installation

Prerequisites

Bun 1.1+ 설치:

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Install CLI

bun install -g akiflow-toolkit
af --help

Platform Support

Platform

Runtime

CLI core

MCP server

Auto auth (browser)

Status

macOS (arm64/x64)

Bun 1.1+

✅

✅

✅ Chrome/Arc/Brave/Edge/Safari

Fully supported

Linux (x64/arm64)

Bun 1.1+

✅

✅

❌ (manual af auth only)

Partial — see docs/tasks/linux-support.md

Windows (x64)

Bun 1.1+

✅

✅

❌ (manual af auth only)

Partial — see docs/tasks/windows-support.md

macOS

자동 인증 포함 전체 기능이 동작합니다.

bun install -g akiflow-toolkit
af auth        # Chrome/Arc/Brave/Edge/Safari에서 자동 토큰 추출
af ls

Linux

CLI 및 MCP는 정상 동작합니다. Chrome cookie 자동 추출은 미구현(libsecret 미연동)이므로 수동 인증을 사용합니다.

bun install -g akiflow-toolkit

# 수동 인증: Akiflow 웹 로그인 후 DevTools → Network → request headers에서
# Bearer <JWT>를 복사해 붙여넣기
af auth

af ls

제약 사항:

  • Chrome cookie 기반 auto-auth 미지원

  • Safari 관련 기능 없음 (Apple 전용 브라우저)

Windows

CLI 및 MCP는 동작합니다. DPAPI(Windows 쿠키 암호화) 미연동으로 Chrome cookie 자동 추출은 불가능.

PowerShell에서:

bun install -g akiflow-toolkit
af auth        # 수동 입력
af ls

제약 사항:

  • Bun Windows arm64는 실험 단계 (x64 권장)

  • PowerShell용 completion 스크립트 미제공 (bash/zsh/fish만 지원)

  • Chrome cookie 기반 auto-auth 미지원

From Source (development)

git clone https://github.com/kty1965/akiflow-toolkit.git
cd akiflow-toolkit
bun install
bun run dev

Quick Start

Coming soon after initial implementation.

# Authenticate (auto-extracts from browser)
af auth

# Use CLI
af ls
af add "New task" --today

# Setup MCP for Claude Code
af setup claude-code

Verifying authentication

After af auth, you can confirm the CLI is talking to the real Akiflow API at four levels of depth:

# 1. Is a credential stored?
af auth status
# → Authenticated: active
#     source: indexeddb
#     expiresAt: 2026-04-19T13:28:30.768Z

# 2. Does the stored token actually reach Akiflow API? (diagnostic probe)
bun run scripts/mcp-api-probe.ts
# → ✓ Akiflow API reachable AND token accepted.
#   status 200 OK, body length 5MB+

# 3. Can a real MCP client spawn the server and round-trip a task?
bun run scripts/mcp-live-demo.ts
# → runs 9 steps: spawn → tools/list → auth_status → READ precheck
#   → create_task → verify inbox → complete_task → verify done
# A clean run ends with "✓ All Tier 2 E2E checks passed."

# 4. Try it from your editor
#    MCP: register `af --mcp` in ~/.claude.json and ask
#    Claude Code "오늘 할 일 보여줘".

If something fails, read docs/akiflow-token-acquisition.md — it walks through the dual auth scheme (Laravel session cookie vs OAuth JWT), the 4-tier extraction cascade (IndexedDB → Cookie → Safari → Manual), the withAuth recovery sequence, and six known failure modes with concrete fixes.

Most common remedy when auth_status shows source: cookie but API calls throw fetch failed / Header has invalid value:

osascript -e 'tell application "Google Chrome" to quit'   # release leveldb LOCK
bun run src/index.ts auth logout
bun run src/index.ts auth                                 # re-scan IndexedDB
bun run src/index.ts auth status                          # expect source: indexeddb

Documentation

Development

Prerequisites

  • Bun >= 1.0.0

  • pre-commit (brew install pre-commit or pip install pre-commit)

Setup

git clone https://github.com/kty1965/akiflow-toolkit.git
cd akiflow-toolkit
bun install
pre-commit install --install-hooks

Commands

bun run dev          # Hot reload 개발 모드
bun test             # 테스트 실행
bun run lint         # Biome 린트
bun run build        # npm 배포용 dist/ 빌드
bun run build:binary # 크로스 플랫폼 바이너리 빌드

Local MCP registration (before npm publish)

Until akiflow-toolkit lands on npm, you can still use it from Claude Code / Cursor / Claude Desktop by building a standalone binary and symlinking it into your PATH. af setup performs an atomic merge-write on the editor config, so any existing mcpServers entries are preserved.

Install

# 1. Build a self-contained binary for your platform (Bun runtime embedded)
bun run build:darwin-arm64   # Apple Silicon
# bun run build:darwin-x64   # Intel Mac
# bun run build:linux-x64    # Linux x64
# bun run build:linux-arm64  # Linux arm64

# 2. Symlink into a PATH directory (no sudo required)
mkdir -p ~/.local/bin
ln -sf "$PWD/dist/af-darwin-arm64" ~/.local/bin/af

# 3. Make sure ~/.local/bin is on PATH
echo "$PATH" | tr ':' '\n' | grep -q "$HOME/.local/bin" \
  || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# Open a new shell, or: source ~/.zshrc

# 4. Smoke check
af --help
af auth status               # expect: source: indexeddb, active

# 5. Register the MCP server in your AI editor
af setup claude-code         # → ~/.claude.json
# af setup cursor            # → ~/.cursor/mcp.json
# af setup claude-desktop    # → ~/Library/Application Support/Claude/... (macOS only)

# 6. Restart the editor, then try a tool call (e.g. "show me today's inbox")

When you edit source code later, only step 1 needs to run again — the symlink keeps pointing at the fresh binary.

Uninstall

# 1. Remove the akiflow entry from every editor config where it was registered
jq 'del(.mcpServers.akiflow)' ~/.claude.json > ~/.claude.json.new && mv ~/.claude.json.new ~/.claude.json
[ -f ~/.cursor/mcp.json ] && jq 'del(.mcpServers.akiflow)' ~/.cursor/mcp.json > ~/.cursor/mcp.json.new && mv ~/.cursor/mcp.json.new ~/.cursor/mcp.json
# Claude Desktop (macOS):
#   CONFIG=~/Library/Application\ Support/Claude/claude_desktop_config.json
#   jq 'del(.mcpServers.akiflow)' "$CONFIG" > "$CONFIG".new && mv "$CONFIG".new "$CONFIG"

# 2. Remove the PATH shim
rm -f ~/.local/bin/af

# 3. (Optional) Drop the compiled binaries
rm -rf dist/

# 4. (Optional) Revoke stored auth credentials
bun run src/index.ts auth logout    # or: rm ~/.config/akiflow/auth.json

# 5. Restart the editor

Disclaimer

See DISCLAIMER.md.

License

MIT © kty1965

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
2dRelease cycle
5Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kty1965/akiflow-toolkit'

If you have feedback or need assistance with the MCP directory API, please join our Discord server