backlog-mcp

MCP-сервер бэклога задач для LLM-агентов. Работает с любым 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 — интерфейс просмотра, подключенный к реально работающему экземпляру

веб-интерфейс backlog-mcp

Что внутри

Это монорепозиторий с 3 пакетами:

Пакет	npm	Что он делает
`packages/server`	`backlog-mcp`	MCP-сервер, HTTP API, CLI
`packages/viewer`	—	Веб-интерфейс на базе `@nisli/core`
`packages/shared`	—	Общие типы сущностей и утилиты для ID

Интерфейс просмотра построен на Nisli, реактивном фреймворке веб-компонентов без зависимостей, опубликованном как @nisli/core. Nisli зародился в этом репозитории, а теперь существует отдельно.

Установка

Добавьте в конфигурацию MCP (.mcp.json или конфигурацию вашего MCP-клиента):

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["-y", "backlog-mcp"]
    }
  }
}

Самостоятельное размещение на Cloudflare (опционально)

Разместите свой собственный всегда доступный удаленный бэклог бесплатно, используя Cloudflare Workers + D1. Доступен с любого устройства или MCP-клиента — локальный серверный процесс не требуется.

Предварительные требования: аккаунт Cloudflare (достаточно бесплатного тарифа), CLI wrangler, GitHub OAuth App.

# 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 App: перейдите в GitHub → Settings → Developer settings → OAuth Apps → New. Установите URL обратного вызова (callback 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 могут подключаться напрямую через удаленный URL MCP — локальный процесс не нужен. Сессии GitHub OAuth используют ротируемые токены обновления, поэтому клиенты могут продлевать доступ без ежедневной повторной аутентификации.

Веб-интерфейс просмотра

Откройте http://localhost:3030 — всегда доступен, пока запущен сервер.

Функции:

Макет с разделением экрана: список задач и детальный просмотр
Поиск Spotlight с гибридным текстовым и семантическим сопоставлением
Обновления в реальном времени через SSE
Хронология активности
Фильтрация по статусу, типу, эпику
Рендеринг Markdown в стиле GitHub с диаграммами Mermaid
Сохранение состояния в URL

Интерфейс просмотра построен на Nisli (@nisli/core).

Типы сущностей

5 типов сущностей, все хранятся как markdown-файлы с YAML frontmatter:

Тип	Префикс	Назначение
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-сервер как отдельный фоновый процесс — обслуживает как MCP-эндпоинт (/mcp), так и веб-интерфейс (/) на порту 3030
Связывает stdio с ним — ваш MCP-клиент общается через stdio, который перенаправляется на HTTP-сервер через mcp-remote
Автоматическое обновление: npx -y всегда загружает последнюю опубликованную версию. Если запущенный сервер является более старой версией, он автоматически завершает работу и перезапускается с новой
Устойчивое восстановление: Если соединение с мостом теряется, супервизор перезапускает его с экспоненциальной задержкой (до 10 попыток). Ошибки соединения, такие как ECONNREFUSED, обнаруживаются и обрабатываются автоматически

HTTP-сервер сохраняется между сессиями агентов — несколько MCP-клиентов могут использовать его совместно. Веб-интерфейс всегда доступен по адресу 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

ADR (архитектурные решения) Backlog документируют важные проектные решения. Полный индекс см. в docs/adr/README.md. ADR Nisli находятся в репозитории Nisli.

Лицензия

MIT

Backlog MCP Server