Backlog MCP Server
backlog-mcp
LLMエージェント向けのタスクバックログMCPサーバーです。Claude、Kiro、Cursor、Codexなど、あらゆるMCPクライアントで動作します。
エージェントはタスクを作成し、進捗を追跡し、成果物を添付し、すべてを横断して検索できます。人間はリアルタイムのWebビューアでエージェントの作業状況を確認できます。
インストール後すぐにローカルで実行可能です。また、Cloudflare Workers + D1でセルフホストすれば、あらゆるデバイスやMCPクライアントからアクセス可能な、常時稼働のリモートバックログとしても利用できます。
クイックスタート: LLMに次のように伝えてください:
Add backlog-mcp to .mcp.json and use it to track tasks
ライブデモ: backlog-mcp-viewer.pages.dev — 実際のホストインスタンスに接続されたビューアUI

構成内容
これは3つのパッケージを含むモノレポです:
パッケージ | npm | 役割 |
MCPサーバー、HTTP API、CLI | ||
— |
| |
— | 共有エンティティ型とIDユーティリティ |
ビューアは、@nisli/core として公開されている依存関係ゼロのリアクティブWebコンポーネントフレームワーク Nisli で構築されています。Nisliはこのリポジトリで始まり、現在は独立して管理されています。
Related MCP server: Task Manager MCP Server
インストール
MCP設定(.mcp.json またはMCPクライアントの設定)に追加してください:
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": ["-y", "backlog-mcp"]
}
}
}Cloudflareでのセルフホスト(オプション)
Cloudflare Workers + D1を使用して、無料で常時稼働のリモートバックログをホストできます。 あらゆるデバイスやMCPクライアントからアクセス可能で、ローカルサーバープロセスは不要です。
前提条件: Cloudflareアカウント(無料枠で十分)、wrangler CLI、GitHub OAuthアプリ。
# 1. Clone and install
git clone https://github.com/gkoreli/backlog-mcp.git
cd backlog-mcp
pnpm install
# 2. Create the D1 database
cd packages/server
npx wrangler d1 create backlog
# Copy the database_id into packages/server/wrangler.jsonc
# 3. Apply the D1 migrations
npx wrangler d1 execute backlog --remote --file=migrations/0001_initial.sql
npx wrangler d1 execute backlog --remote --file=migrations/0002_oauth_refresh_tokens.sql
# 4. Set secrets
npx wrangler secret put JWT_SECRET # any strong random string
npx wrangler secret put API_KEY # your personal API key (for Claude Desktop)
npx wrangler secret put GITHUB_CLIENT_ID # GitHub OAuth App client ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put ALLOWED_GITHUB_USERNAMES # comma-separated: "you,youralt"
# 5. Deploy
npx wrangler deployGitHub OAuthアプリの設定: GitHub → Settings → Developer settings → OAuth Apps → New に移動します。
コールバックURLを https://<your-worker>.workers.dev/oauth/github/callback に設定してください。
デプロイ後、MCPクライアントの設定に追加します:
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://<your-worker>.workers.dev/mcp"]
}
}
}Claude.aiやChatGPTはリモートMCP URL経由で直接接続できるため、ローカルプロセスは不要です。 GitHub OAuthセッションはローテーションされるリフレッシュトークンを使用するため、クライアントは毎日再認証することなくアクセスを更新できます。
Webビューア
http://localhost:3030 を開いてください。サーバー実行中は常に利用可能です。
機能:
タスクリストと詳細表示の分割ペインレイアウト
ハイブリッドテキスト + セマンティックマッチングによるスポットライト検索
SSEによるリアルタイム更新
アクティビティタイムライン
ステータス、タイプ、エピックによるフィルタリング
Mermaid図を含むGitHubスタイルのMarkdownレンダリング
URL状態の永続化
ビューアUIは Nisli (@nisli/core) で構築されています。
エンティティ型
5つのエンティティ型があり、すべてYAMLフロントマター付きのMarkdownファイルとして保存されます:
型 | プレフィックス | 目的 |
Task |
| 作業項目 |
Epic |
| 関連タスクのグループ |
Folder |
| 整理用コンテナ |
Artifact |
| 添付された成果物(調査、設計、ログ) |
Milestone |
| 期日付きの期限目標 |
ステータス値: open, in_progress, blocked, done, cancelled
タスクファイルの例:
---
id: TASK-0001
title: Fix authentication flow
status: open
epic_id: EPIC-0002
parent_id: FLDR-0001
references:
- url: https://github.com/org/repo/issues/123
title: Related issue
evidence:
- Fixed in PR #45
---
The authentication flow has an issue where...MCPツール
backlog_list
backlog_list # Active tasks (open, in_progress, blocked)
backlog_list status=["done"] # Completed tasks
backlog_list type="epic" # Only epics
backlog_list epic_id="EPIC-0002" # Tasks in an epic
backlog_list parent_id="FLDR-0001" # Items in a folder
backlog_list query="authentication" # Search across all fields
backlog_list counts=true # Include counts by status/type
backlog_list limit=50 # Limit resultsbacklog_get
backlog_get id="TASK-0001" # Single item
backlog_get id=["TASK-0001","EPIC-0002"] # Batch getbacklog_create
backlog_create title="Fix bug"
backlog_create title="Fix bug" description="Details..." epic_id="EPIC-0002"
backlog_create title="Q1 Goals" type="epic"
backlog_create title="Research notes" type="artifact" parent_id="TASK-0001"
backlog_create title="v2.0 Release" type="milestone" due_date="2026-03-01"
backlog_create title="Fix bug" source_path="/path/to/spec.md" # Read description from filebacklog_update
backlog_update id="TASK-0001" status="done"
backlog_update id="TASK-0001" status="blocked" blocked_reason=["Waiting on API"]
backlog_update id="TASK-0001" evidence=["Fixed in PR #45"]
backlog_update id="TASK-0001" parent_id="FLDR-0001"
backlog_update id="MLST-0001" due_date="2026-04-01"backlog_delete
backlog_delete id="TASK-0001" # Permanent deletebacklog_search
関連性スコアリング付きのフルテキスト + セマンティックハイブリッド検索:
backlog_search query="authentication bug"
backlog_search query="design decisions" types=["artifact"]
backlog_search query="blocked tasks" status=["blocked"] limit=10
backlog_search query="framework" sort="recent"
backlog_search query="search ranking" include_content=truebacklog_context
タスクの豊富なコンテキスト(親エピック、兄弟、子、相互参照、逆参照、最近のアクティビティ、セマンティックに関連する項目)を取得します:
backlog_context task_id="TASK-0001"
backlog_context task_id="TASK-0001" depth=2 # Grandparent/grandchildren
backlog_context query="search ranking improvements" # Find by description
backlog_context task_id="TASK-0001" include_related=false # Skip semantic searchwrite_resource
MCPサーバー上の既存ファイルを編集します。作成はすべて backlog_create を経由します。
# Edit task body (use str_replace — protects frontmatter)
write_resource uri="mcp://backlog/tasks/TASK-0001.md" \
operation={type: "str_replace", old_str: "old text", new_str: "new text"}
# Insert after a specific line
write_resource uri="mcp://backlog/tasks/TASK-0001.md" \
operation={type: "insert", insert_line: 5, new_str: "inserted line"}
# Append to a file
write_resource uri="mcp://backlog/resources/log.md" \
operation={type: "append", new_str: "New entry"}操作: str_replace(完全一致、一意である必要あり)、insert(行番号の後)、append(ファイルの末尾)。
仕組み
npx -y backlog-mcp(デフォルトのMCP設定)を実行すると、以下の処理が行われます:
永続的なHTTPサーバーをバックグラウンドプロセスとして起動 — MCPエンドポイント (
/mcp) とWebビューア (/) の両方をポート3030で提供します。stdioをブリッジ — MCPクライアントはstdio経由で通信し、それが
mcp-remoteを介してHTTPサーバーに転送されます。自動更新:
npx -yは常に最新の公開バージョンを取得します。実行中のサーバーが古いバージョンの場合、自動的にシャットダウンされ、新しいバージョンで再起動されます。回復機能: ブリッジの接続が切断された場合、スーパーバイザーが指数バックオフ(最大10回のリトライ)で再起動します。
ECONNREFUSEDのような接続エラーは自動的に検出され、処理されます。
HTTPサーバーはエージェントセッションをまたいで永続化されるため、複数のMCPクライアントで共有可能です。Webビューアは常に http://localhost:3030 で利用可能です。
CLI
npx経由の全コマンド:
$ npx backlog-mcp status
Server is running on port 3030
Version: 0.44.0
Data directory: /Users/you/.backlog
Task count: 451
Uptime: 3515s
Viewer: http://localhost:3030/
MCP endpoint: http://localhost:3030/mcp
$ npx backlog-mcp stop
Stopping server on port 3030...
Server stopped
$ npx backlog-mcp status
Server is not running出力例:
$ npx backlog-mcp status
Server is running on port 3030
Version: 0.44.0
Data directory: /Users/you/.backlog
Task count: 451
Uptime: 3515s
Viewer: http://localhost:3030/
MCP endpoint: http://localhost:3030/mcp
$ npx backlog-mcp stop
Stopping server on port 3030...
Server stopped
$ npx backlog-mcp status
Server is not runningCLIは、人間がエージェントのバックグラウンドサーバーを検査・管理するために存在します。デフォルトモードではデタッチされたプロセスが生成されるため、status で確認し、stop でシャットダウンする必要があります。
serve はHTTPサーバーをデタッチせずにフォアグラウンドで実行します。デバッグ、Dockerコンテナ、またはMCPクライアントなしでの実行に便利です。通常の使用では必要ありません。デフォルトコマンドがすべてを処理します。
設定
BACKLOG_DATA_DIR=~/.backlog # Where to store tasks (default: data/tasks/)
BACKLOG_VIEWER_PORT=3030 # HTTP server portローカル開発用に .env ファイルを作成してください(.env.example を参照)。
開発
git clone https://github.com/gkoreli/backlog-mcp.git
cd backlog-mcp
pnpm install
pnpm build # Build all packages
pnpm test # Run all workspace tests
pnpm dev # Server + viewer with hot reloadアーキテクチャ
packages/
├── server/ # MCP server, search, context hydration, storage
├── viewer/ # Web UI built with @nisli/core
└── shared/ # Entity types, ID utilities
docs/
├── adr/ # backlog-mcp architecture decision records
└── framework-adr/ # Pointer to Nisli ADRsBacklogのADR(アーキテクチャ決定記録)は重要な設計決定を文書化しています。完全なインデックスは docs/adr/README.md を参照してください。NisliのADRは Nisliリポジトリ にあります。
ライセンス
MIT
Available Tools
23 toolsbacklog_accept_adrA
Use when ratifying an existing proposed ADR.
Inputs: id (required), as.
backlog_attach_artifactB
Use when attaching an artifact to a project item. parent_id is required.
Inputs: title (required), parent_id (required), as, path, +3 more.
backlog_block_taskC
Use when blocking a task with a reason.
Inputs: id (required), blocked_reason (required), as.
backlog_capture_promptC
Use when preserving a verbatim human directive as a chronological project prompt.
Inputs: title (required), content (required), as, date, +3 more.
backlog_capture_referenceA
Use when recording an external technology, prior-art system, or benchmark this project builds on — with authoritative citations and the project's adopt/park/reject relationship to it.
Inputs: title (required), content (required), bears_on (required), category (required), +4 more.
backlog_capture_requirementC
Use when recording a human or system requirement in the current project.
Inputs: title (required), content (required), as, date, +11 more.
backlog_complete_taskC
Use when completing a task, optionally with evidence.
Inputs: id (required), as, evidence.
backlog_consolidation_candidatesA
List clusters of episodic memories that are ripe for consolidation into durable knowledge. Consolidator workflow: (1) call this and take ripe bundles; (2) per bundle, read members (backlog_get on MEMO- ids for depth), then write ONE narrative memory via backlog_remember({ layer: "semantic"|"procedural", derived: true, entity_refs: [member MEMO- ids + key source entities], context }) — a self-contained story, not fragments; (3) retire the members via backlog_forget({ ids }) so they stop appearing here while staying auditable; (4) track your progress with a backlog_remember state_key like "consolidation.watermark.".
Inputs: home, limit, context, min_count, +4 more.
backlog_contradictionsA
List structural contradictions in memory: sets of ≥2 LIVE memories that share one state_key (e.g. "db.primary"), which should never happen — a new memory with a state_key auto-expires the previous holder. Each set means two beliefs about the same fact are both active. Resolution is yours, never automatic: pick the correct member, then either backlog_remember({ content, state_key, supersedes: }) to record the right value and retire the rest, or backlog_forget({ ids: [] }) to expire the wrong ones. Read members with backlog_get for full context before deciding. Set candidates: true to list semantic collision candidates instead: nearby live facts that deserve review, never contradiction verdicts.
Inputs: home, candidates, project_root.
backlog_create_workB
Use when creating a project work item. Pass parent_id when known; parentless work surfaces as unfiled at wakeup.
Inputs: title (required), as, content, parent_id, +1 more.
backlog_deleteC
Delete an item permanently.
Inputs: id (required), as, home, project_root.
backlog_forgetA
Retract memories — soft-expire them so recall stops returning them (the record stays auditable in the viewer). Use when knowledge is wrong or obsolete and there is no replacement (if there IS a replacement, use backlog_remember with supersedes instead). expired:true garbage-collects already-expired memories.
Inputs: ids, home, layer, context, +3 more.
backlog_getA
Get full details by ID. Accepts task IDs (TASK-0001, EPIC-0002), document paths (README.md, docs/adr/0001-example.md), or MCP resource URIs (mcp://backlog/resources/design.md). Works for any item regardless of status. Pass context:true when starting work on an entity to also see its relational neighborhood as stubs.
Inputs: id (required), home, depth, context, +1 more.
backlog_organize_folderA
Use when creating a folder to organize project items. Pass parent_id when known; parentless work surfaces as unfiled at wakeup.
Inputs: title (required), as, content, parent_id.
backlog_pause_cronB
Use when pausing a scheduled intake.
Inputs: id (required), as.
backlog_recallA
Recall memories — knowledge and episodes captured across sessions. Returns STUBS (title + one-line digest + provenance) by default; expand interesting ones with backlog_get(MEMO-id), or pass full:true for bodies. Weigh a stub's trust BEFORE hydrating: age_days (on the knowledge's own timeline), uses/idle_days (recall demand), supersedes (this is a correction), derived (consolidator inference), kind (current/historical/plan/preference/timeless). Old + never-used = treat as hypothesis, not truth. Distinct from backlog_search (live entities). Use to answer "how do we deploy?", "have I hit this before?", "what did I finish about X?". Memories point back to source entities via entity_id.
Inputs: query (required), full, home, tags, +5 more.
backlog_rememberA
Write a durable memory — a stable fact, a procedure, or a preference you should know next session. Use when you learn something worth keeping: "this repo deploys via wrangler", "Goga prefers terse evidence bullets". To CORRECT existing knowledge, pass supersedes (the old MEMO- id is expired, lineage kept) or state_key (previous holders of the same evolving fact are closed). The optional collision_candidates receipt is tri-state: [] means the advisory scan completed clean; a non-empty array means nearby facts deserve adjudication; absent means the advisory scan did not run or failed, not that the write failed. Do not use for task events — completions are captured automatically.
Inputs: title (required), content (required), as, home, +11 more.
backlog_resume_cronC
Use when resuming a scheduled intake.
Inputs: id (required), as.
backlog_schedule_cronB
Use when scheduling recurring project intake. Pass parent_id when known; parentless work surfaces as unfiled at wakeup.
Inputs: title (required), command (required), schedule (required), as, +3 more.
backlog_searchA
Search across all indexed backlog substrates and generic resources. Returns relevance-ranked results with match context. Use this for discovery; use backlog_list for filtering by status/type.
Inputs: query (required), home, sort, limit, +6 more.
backlog_supersede_adrA
Use when a newer ADR replaces an accepted or living ADR while preserving lineage.
Inputs: superseded_id (required), replacement_id (required), as.
backlog_wakeupA
Dense session-start briefing: active tasks, current epics, project constraints (requirements as stubs, violated/at-risk first — treat these as standing product intent), recent completions (with evidence snippets), recent activity, and the home-wide unfiled work count. No focal entity required — use this at the start of every session to understand what you were working on. Optional scope narrows the entity sections to a folder, milestone, or epic; unfiled remains home-wide because parentless work has no subtree ancestry. Optional operation resumes a mid-flight operation document: its live state becomes the briefing's FOCUS centerpiece and the rest of the briefing yields budget to it.
Inputs: home, scope, operation, max_activity, +4 more.
write_resourceA
Use when you want backlog-mcp to validate and canonically persist an existing entity edit before reporting success. For ordinary repository prose edits, use your native Edit tool; reconciliation updates indexes and diagnostics afterward. Create and transition entities through the substrate-declared intent tools.
The
appendcommand will add content to the end of the body, automatically adding a newline if needed. Notes for using thestr_replacecommand:The
old_strparameter should match EXACTLY one or more consecutive lines from the original body. Be mindful of whitespaces!If the
old_strparameter is not unique in the body, the replacement will not be performed. Include enough context to make it unique.The
new_strparameter should contain the edited lines that should replace theold_str
Inputs: id (required), operation (required), as, home, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Some tools are clearly distinct (backlog_get, backlog_delete, backlog_search), but overlap exists among 'capture' tools (backlog_capture_prompt, backlog_capture_reference, backlog_capture_requirement) and 'create' tools (backlog_create_work, backlog_organize_folder, backlog_schedule_cron) that may confuse selection. Also, backlog_wakeup and backlog_recall both serve retrieval purposes, but their contexts differ; the descriptions do help to differentiate these.
All tool names are lowercase with underscores, but the verb style varies: some use verb_noun (backlog_get, backlog_delete), others use verb_object (backlog_complete_task, backlog_attach_artifact), and some lack a clear verb-object structure (backlog_consolidation_candidates, backlog_contradictions). The consistent prefix 'backlog_' helps, but patterns like 'create' vs 'capture' and 'organize' are not uniform.
23 tools is a fairly large set, but it covers the domain of a project management/knowledge memory server well. Each tool serves a distinct function — CRUD for work items, ADR management, memory operations, scheduling, and organization. Slightly heavy, but justified given the breadth of features (tasks, ADRs, memories, scheduling).
The tool surface is extensive, covering work item lifecycle (create, get, delete, complete, block), ADR handling (accept, supersede), memory management (remember, recall, forget, consolidation), and project organization (folders, attachments, requirements). Minor gaps include no explicit 'update_work' or 'unblock_task', but these may be handled via write_resource or other mechanisms.
Maintenance
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
A graph-based task manager your agent can read and update: tasks, dependencies, blockers.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Create, search, and list Changologs logs and tasks
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables users to manage tasks through a simple JSON file interface. Provides basic task management functionality by reading and writing to a configurable tasks.json file.20 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables task management through natural language with full CRUD operations including add, list, update, complete, and delete tasks with JSON persistence.ISC
- FlicenseNot gradedqualityDmaintenanceManages TODO tasks with operations like add, list, complete, update, and delete, stored in a JSON file.-
- AlicenseBqualityDmaintenanceEnables task management via MCP tools for creating, listing, updating, completing, and deleting tasks with JSON file storage.6ISC