backlog-mcp

LLM 에이전트를 위한 작업 백로그 MCP 서버입니다. Claude, Kiro, Cursor, Codex 등 모든 MCP 클라이언트와 호환됩니다.

에이전트는 작업을 생성하고, 진행 상황을 추적하며, 아티팩트를 첨부하고, 모든 항목을 검색할 수 있습니다. 사용자는 실시간 웹 뷰어를 통해 에이전트가 수행 중인 작업을 확인할 수 있습니다.

즉시 로컬에서 실행 가능합니다. 또한 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 웹 뷰어

포함된 내용

이 저장소는 3개의 패키지로 구성된 모노레포입니다:

패키지	npm	역할
`packages/server`	`backlog-mcp`	MCP 서버, HTTP API, CLI
`packages/viewer`	—	`@nisli/core` 기반 웹 UI
`packages/shared`	—	공유 엔티티 유형 및 ID 유틸리티

뷰어는 @nisli/core로 게시된 의존성 없는 반응형 웹 컴포넌트 프레임워크인 Nisli로 구축되었습니다. 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 세션은 순환되는 리프레시 토큰을 사용하므로 클라이언트가 매일 재인증할 필요 없이 액세스 권한을 갱신할 수 있습니다.

웹 뷰어

http://localhost:3030을 여세요 — 서버가 실행 중일 때 항상 사용할 수 있습니다.

기능:

작업 목록 및 상세 보기가 포함된 분할 창 레이아웃
텍스트 + 의미론적 매칭을 결합한 스포트라이트 검색
SSE를 통한 실시간 업데이트
활동 타임라인
상태, 유형, 에픽별 필터링
Mermaid 다이어그램을 지원하는 GitHub 스타일 마크다운 렌더링
URL 상태 유지

뷰어 UI는 Nisli (@nisli/core)로 구축되었습니다.

엔티티 유형

YAML 프런트매터가 포함된 마크다운 파일로 저장되는 5가지 엔티티 유형:

유형	접두사	목적
작업(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)와 웹 뷰어(/)를 모두 제공합니다.
stdio 브리지: MCP 클라이언트는 stdio를 통해 통신하며, 이는 mcp-remote를 통해 HTTP 서버로 전달됩니다.
자동 업데이트: 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

Backlog ADR은 중요한 설계 결정을 문서화합니다. 전체 인덱스는 docs/adr/README.md를 참조하세요. Nisli ADR은 Nisli 저장소에 있습니다.

라이선스

MIT

Backlog MCP Server