backlog-mcp

Ein Aufgaben-Backlog-MCP-Server für LLM-Agenten. Funktioniert mit jedem MCP-Client — Claude, Kiro, Cursor, Codex usw.

Agenten erstellen Aufgaben, verfolgen den Fortschritt, hängen Artefakte an und durchsuchen alles. Menschen erhalten einen Echtzeit-Web-Viewer, um zu sehen, was Agenten tun.

Läuft sofort lokal. Kann auch auf Cloudflare Workers + D1 selbst gehostet werden, für ein kostenloses, ständig verfügbares Remote-Backlog, das von jedem Gerät oder MCP-Client aus zugänglich ist.

Schnellstart: Sagen Sie Ihrem LLM: Add backlog-mcp to .mcp.json and use it to track tasks

Live-Demo: backlog-mcp-viewer.pages.dev — die Viewer-UI, verbunden mit einer echten gehosteten Instanz

backlog-mcp web viewer

Was ist enthalten

Dies ist ein Monorepo mit 3 Paketen:

Paket	npm	Was es tut
`packages/server`	`backlog-mcp`	MCP-Server, HTTP-API, CLI
`packages/viewer`	—	Web-UI, basierend auf `@nisli/core`
`packages/shared`	—	Gemeinsame Entitätstypen und ID-Dienstprogramme

Der Viewer wurde mit Nisli erstellt, einem reaktiven Web-Component-Framework ohne Abhängigkeiten, das als @nisli/core veröffentlicht wurde. Nisli begann in diesem Repository und existiert nun separat.

Installation

Fügen Sie es zu Ihrer MCP-Konfiguration hinzu (.mcp.json oder Ihre MCP-Client-Konfiguration):

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

Self-Hosting auf Cloudflare (Optional)

Hosten Sie Ihr eigenes, ständig verfügbares Remote-Backlog kostenlos mit Cloudflare Workers + D1. Von jedem Gerät oder MCP-Client aus zugänglich — kein lokaler Serverprozess erforderlich.

Voraussetzungen: Cloudflare-Konto (kostenloser Tarif reicht aus), wrangler CLI, eine 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-Einrichtung: Gehen Sie zu GitHub → Settings → Developer settings → OAuth Apps → New. Setzen Sie die Callback-URL auf https://<your-worker>.workers.dev/oauth/github/callback.

Nach der Bereitstellung fügen Sie es zu Ihrer MCP-Client-Konfiguration hinzu:

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-worker>.workers.dev/mcp"]
    }
  }
}

Claude.ai und ChatGPT können sich direkt über die Remote-MCP-URL verbinden — kein lokaler Prozess erforderlich. GitHub OAuth-Sitzungen verwenden rotierende Refresh-Tokens, sodass Clients den Zugriff erneuern können, ohne sich täglich neu authentifizieren zu müssen.

Web-Viewer

Öffnen Sie http://localhost:3030 — immer verfügbar, wenn der Server läuft.

Funktionen:

Layout mit geteiltem Bereich für Aufgabenliste und Detailansicht
Spotlight-Suche mit hybrider Text- + semantischer Übereinstimmung
Echtzeit-Updates via SSE
Aktivitäts-Timeline
Filtern nach Status, Typ, Epic
Markdown-Rendering im GitHub-Stil mit Mermaid-Diagrammen
URL-Zustandspersistenz

Die Viewer-UI wurde mit Nisli (@nisli/core) erstellt.

Entitätstypen

5 Entitätstypen, alle als Markdown-Dateien mit YAML-Frontmatter gespeichert:

Typ	Präfix	Zweck
Task	`TASK-0001`	Arbeitselemente
Epic	`EPIC-0001`	Gruppen zusammengehöriger Aufgaben
Folder	`FLDR-0001`	Organisationscontainer
Artifact	`ARTF-0001`	Angehängte Ausgaben (Recherche, Designs, Protokolle)
Milestone	`MLST-0001`	Zeitgebundene Ziele mit Fälligkeitsdaten

Statuswerte: open, in_progress, blocked, done, cancelled

Beispiel für eine Aufgabendatei:

---
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-Tools

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

Hybride Volltext- + semantische Suche mit Relevanzbewertung:

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

Erhalten Sie umfassenden Kontext für eine Aufgabe — übergeordnetes Epic, Geschwister, Kinder, Querverweise, Rückverweise, kürzliche Aktivitäten und semantisch verwandte Elemente:

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

Bearbeiten Sie vorhandene Dateien auf dem MCP-Server. Alle Erstellungen erfolgen über 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"}

Operationen: str_replace (exakte Übereinstimmung, muss eindeutig sein), insert (nach Zeilennummer), append (Dateiende).

Funktionsweise

Das Ausführen von npx -y backlog-mcp (die Standard-MCP-Konfiguration) bewirkt Folgendes:

Startet einen persistenten HTTP-Server als losgelösten Hintergrundprozess — bedient sowohl den MCP-Endpunkt (/mcp) als auch den Web-Viewer (/) auf Port 3030
Überbrückt stdio dorthin — Ihr MCP-Client kommuniziert über stdio, das via mcp-remote an den HTTP-Server weitergeleitet wird
Auto-Updates: npx -y zieht immer die neueste veröffentlichte Version. Wenn der laufende Server eine ältere Version ist, wird er automatisch heruntergefahren und mit der neuen neu gestartet
Resiliente Wiederherstellung: Wenn die Brücke die Verbindung verliert, startet ein Supervisor sie mit exponentiellem Backoff neu (bis zu 10 Wiederholungsversuche). Verbindungsfehler wie ECONNREFUSED werden erkannt und automatisch behandelt

Der HTTP-Server bleibt über Agentensitzungen hinweg bestehen — mehrere MCP-Clients können ihn gemeinsam nutzen. Der Web-Viewer ist immer unter http://localhost:3030 verfügbar.

CLI

Alle Befehle via 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)

Beispielausgaben:

$ 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

Die CLI existiert für Menschen, um den Hintergrundserver, den Agenten verwenden, zu inspizieren und zu verwalten. Da der Standardmodus einen losgelösten Prozess startet, benötigen Sie status, um ihn zu überprüfen, und stop, um ihn herunterzufahren.

serve führt den HTTP-Server im Vordergrund statt losgelöst aus — nützlich für Debugging, Docker-Container oder den Betrieb ohne MCP-Client. Bei normaler Verwendung benötigen Sie dies nie; der Standardbefehl erledigt alles.

Konfiguration

BACKLOG_DATA_DIR=~/.backlog    # Where to store tasks (default: data/tasks/)
BACKLOG_VIEWER_PORT=3030       # HTTP server port

Erstellen Sie eine .env-Datei für die lokale Entwicklung — siehe .env.example.

Entwicklung

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

Architektur

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-ADRs dokumentieren wichtige Designentscheidungen. Siehe docs/adr/README.md für den vollständigen Index. Nisli-ADRs befinden sich im Nisli-Repository.

Lizenz

MIT

Backlog MCP Server