backlog-mcp

Un servidor MCP de backlog de tareas para agentes LLM. Funciona con cualquier cliente MCP: Claude, Kiro, Cursor, Codex, etc.

Los agentes crean tareas, realizan un seguimiento del progreso, adjuntan artefactos y buscan en todo. Los humanos obtienen un visor web en tiempo real para ver lo que están haciendo los agentes.

Se ejecuta localmente de forma inmediata. También se puede autoalojar en Cloudflare Workers + D1 para obtener un backlog remoto gratuito y siempre activo, accesible desde cualquier dispositivo o cliente MCP.

Inicio rápido: Dile a tu LLM: Add backlog-mcp to .mcp.json and use it to track tasks

Demo en vivo: backlog-mcp-viewer.pages.dev — la interfaz de usuario del visor conectada a una instancia alojada real

visor web de backlog-mcp

Qué hay dentro

Este es un monorepo con 3 paquetes:

Paquete	npm	Qué hace
`packages/server`	`backlog-mcp`	Servidor MCP, API HTTP, CLI
`packages/viewer`	—	Interfaz web construida sobre `@nisli/core`
`packages/shared`	—	Tipos de entidad compartidos y utilidades de ID

El visor está construido con Nisli, un framework de componentes web reactivos sin dependencias publicado como @nisli/core. Nisli comenzó en este repositorio y ahora vive por separado.

Instalación

Añádelo a tu configuración de MCP (.mcp.json o la configuración de tu cliente MCP):

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

Autoalojamiento en Cloudflare (Opcional)

Aloja tu propio backlog remoto siempre activo de forma gratuita usando Cloudflare Workers + D1. Accesible desde cualquier dispositivo o cliente MCP: no se requiere proceso de servidor local.

Requisitos previos: Cuenta de Cloudflare (el nivel gratuito es suficiente), CLI wrangler, una aplicación OAuth de GitHub.

# 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

Configuración de la aplicación OAuth de GitHub: ve a GitHub → Settings → Developer settings → OAuth Apps → New. Establece la URL de callback en https://<your-worker>.workers.dev/oauth/github/callback.

Una vez desplegado, añádelo a la configuración de tu cliente MCP:

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

Claude.ai y ChatGPT pueden conectarse directamente a través de la URL remota de MCP: no se necesita ningún proceso local. Las sesiones de OAuth de GitHub utilizan tokens de actualización rotativos para que los clientes puedan renovar el acceso sin necesidad de volver a autenticarse diariamente.

Visor Web

Abre http://localhost:3030: siempre disponible cuando el servidor está en ejecución.

Características:

Diseño de panel dividido con lista de tareas y vista detallada
Búsqueda destacada con coincidencia híbrida de texto + semántica
Actualizaciones en tiempo real mediante SSE
Cronología de actividad
Filtrar por estado, tipo, épica
Renderizado de markdown estilo GitHub con diagramas Mermaid
Persistencia del estado de la URL

La interfaz de usuario del visor está construida con Nisli (@nisli/core).

Tipos de entidad

5 tipos de entidad, todos almacenados como archivos markdown con frontmatter YAML:

Tipo	Prefijo	Propósito
Tarea	`TASK-0001`	Elementos de trabajo
Épica	`EPIC-0001`	Grupos de tareas relacionadas
Carpeta	`FLDR-0001`	Contenedores organizativos
Artefacto	`ARTF-0001`	Salidas adjuntas (investigación, diseños, registros)
Hito	`MLST-0001`	Objetivos con fecha límite

Valores de estado: open, in_progress, blocked, done, cancelled

Ejemplo de archivo de tarea:

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

Herramientas 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

Búsqueda híbrida de texto completo + semántica con puntuación de relevancia:

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

Obtén un contexto enriquecido para una tarea: épica principal, tareas hermanas, hijas, referencias cruzadas, referencias inversas, actividad reciente y elementos semánticamente relacionados:

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

Edita archivos existentes en el servidor MCP. Toda la creación pasa por 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"}

Operaciones: str_replace (coincidencia exacta, debe ser única), insert (después del número de línea), append (final del archivo).

Cómo funciona

Ejecutar npx -y backlog-mcp (la configuración predeterminada de MCP) hace lo siguiente:

Inicia un servidor HTTP persistente como un proceso en segundo plano separado: sirve tanto el endpoint MCP (/mcp) como el visor web (/) en el puerto 3030
Conecta stdio a él: tu cliente MCP se comunica a través de stdio, que se reenvía al servidor HTTP a través de mcp-remote
Actualizaciones automáticas: npx -y siempre descarga la última versión publicada. Si el servidor en ejecución es una versión anterior, se cierra automáticamente y se reinicia con la nueva
Recuperación resiliente: Si el puente pierde la conexión, un supervisor lo reinicia con retroceso exponencial (hasta 10 reintentos). Los errores de conexión como ECONNREFUSED se detectan y manejan automáticamente

El servidor HTTP persiste durante las sesiones del agente: varios clientes MCP pueden compartirlo. El visor web siempre está disponible en http://localhost:3030.

CLI

Todos los comandos a través de 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)

Salidas de muestra:

$ 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

La CLI existe para que los humanos inspeccionen y gestionen el servidor en segundo plano que utilizan los agentes. Dado que el modo predeterminado genera un proceso separado, necesitas status para comprobarlo y stop para cerrarlo.

serve ejecuta el servidor HTTP en primer plano en lugar de separado: útil para depuración, contenedores Docker o ejecución sin un cliente MCP. En el uso normal nunca lo necesitarás; el comando predeterminado maneja todo.

Configuración

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

Crea un archivo .env para el desarrollo local: consulta .env.example.

Desarrollo

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

Arquitectura

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

Los ADR de Backlog documentan decisiones de diseño importantes. Consulta docs/adr/README.md para ver el índice completo. Los ADR de Nisli viven en el repositorio de Nisli.

Licencia

MIT

Backlog MCP Server