backlog-mcp

一个用于 LLM 代理的任务积压 MCP 服务器。适用于任何 MCP 客户端 — Claude、Kiro、Cursor、Codex 等。

代理可以创建任务、跟踪进度、附加制品并搜索所有内容。人类可以通过实时网页查看器查看代理正在执行的操作。

开箱即用，可在本地运行。也可以自托管在 Cloudflare Workers + D1 上，实现免费、始终在线的远程积压，可从任何设备或 MCP 客户端访问。

快速开始：告诉你的 LLM：Add backlog-mcp to .mcp.json and use it to track tasks

在线演示：backlog-mcp-viewer.pages.dev — 连接到真实托管实例的查看器 UI

backlog-mcp web viewer

内容概览

这是一个包含 3 个包的 monorepo：

包	npm	功能
`packages/server`	`backlog-mcp`	MCP 服务器、HTTP API、CLI
`packages/viewer`	—	基于 `@nisli/core` 构建的 Web UI
`packages/shared`	—	共享实体类型和 ID 工具

查看器使用 Nisli 构建，这是一个发布为 @nisli/core 的零依赖响应式 Web 组件框架。Nisli 最初诞生于此仓库，现已独立存在。

安装

添加到你的 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 deploy

GitHub 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 实现实时更新
活动时间轴
按状态、类型、史诗（Epic）过滤
带有 Mermaid 图表的 GitHub 风格 Markdown 渲染
URL 状态持久化

查看器 UI 使用 Nisli (@nisli/core) 构建。

实体类型

5 种实体类型，全部存储为带有 YAML 前置元数据的 markdown 文件：

类型	前缀	用途
任务 (Task)	`TASK-0001`	工作项
史诗 (Epic)	`EPIC-0001`	相关任务组
文件夹 (Folder)	`FLDR-0001`	组织容器
制品 (Artifact)	`ARTF-0001`	附加输出（研究、设计、日志）
里程碑 (Milestone)	`MLST-0001`	有截止日期的限时目标

状态值： 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 results

backlog_get

backlog_get id="TASK-0001"                # Single item
backlog_get id=["TASK-0001","EPIC-0002"]  # Batch get

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

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

backlog_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=true

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

write_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 服务器 作为分离的后台进程 — 在 3030 端口同时提供 MCP 端点 (/mcp) 和 Web 查看器 (/)
桥接 stdio — 你的 MCP 客户端通过 stdio 通信，该通信通过 mcp-remote 转发到 HTTP 服务器
自动更新：npx -y 总是拉取最新发布的版本。如果运行中的服务器是旧版本，它会自动关闭并使用新版本重启
弹性恢复：如果桥接连接丢失，监控程序会以指数退避方式（最多重试 10 次）重启它。像 ECONNREFUSED 这样的连接错误会被自动检测并处理

HTTP 服务器在代理会话间保持持久 — 多个 MCP 客户端可以共享它。Web 查看器始终在 http://localhost:3030 可用。

CLI

所有命令均通过 npx 执行：

npx backlog-mcp                # Start stdio bridge + auto-spawn HTTP server (default)
npx backlog-mcp status         # Check server status
npx backlog-mcp stop           # Stop the server
npx backlog-mcp version        # Show version
npx backlog-mcp serve          # Run HTTP server in foreground (optional, see below)

输出示例：

$ 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

CLI 的存在是为了让人类检查和管理代理使用的后台服务器。由于默认模式会生成一个分离的进程，你需要使用 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 ADRs

Backlog ADR 记录了重要的设计决策。请参阅 docs/adr/README.md 获取完整索引。Nisli ADR 位于 Nisli 仓库。

许可证

MIT

Backlog MCP Server