Skip to main content
Glama
deenesjakoruzh
gkoreli

Backlog MCP Server

by gkoreli
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

backlog-mcp

LLMエージェント向けのタスクバックログMCPサーバーです。Claude、Kiro、Cursor、Codexなど、あらゆるMCPクライアントで動作します。

エージェントはタスクを作成し、進捗を追跡し、成果物を添付し、すべてを横断して検索できます。人間はリアルタイムのWebビューアでエージェントの作業状況を確認できます。

インストール後すぐにローカルで実行可能です。また、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つのパッケージを含むモノレポです：

パッケージ

npm

役割

packages/server

backlog-mcp

MCPサーバー、HTTP API、CLI

packages/viewer

—

@nisli/core で構築されたWeb UI

packages/shared

—

共有エンティティ型とIDユーティリティ

ビューアは、@nisli/core として公開されている依存関係ゼロのリアクティブWebコンポーネントフレームワーク 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セッションはローテーションされるリフレッシュトークンを使用するため、クライアントは毎日再認証することなくアクセスを更新できます。

Webビューア

http://localhost:3030 を開いてください。サーバー実行中は常に利用可能です。

機能:

  • タスクリストと詳細表示の分割ペインレイアウト

  • ハイブリッドテキスト + セマンティックマッチングによるスポットライト検索

  • SSEによるリアルタイム更新

  • アクティビティタイムライン

  • ステータス、タイプ、エピックによるフィルタリング

  • 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設定）を実行すると、以下の処理が行われます：

  1. 永続的なHTTPサーバーをバックグラウンドプロセスとして起動 — MCPエンドポイント (/mcp) とWebビューア (/) の両方をポート3030で提供します。

  2. stdioをブリッジ — MCPクライアントはstdio経由で通信し、それが mcp-remote を介してHTTPサーバーに転送されます。

  3. 自動更新: npx -y は常に最新の公開バージョンを取得します。実行中のサーバーが古いバージョンの場合、自動的にシャットダウンされ、新しいバージョンで再起動されます。

  4. 回復機能: ブリッジの接続が切断された場合、スーパーバイザーが指数バックオフ（最大10回のリトライ）で再起動します。ECONNREFUSED のような接続エラーは自動的に検出され、処理されます。

HTTPサーバーはエージェントセッションをまたいで永続化されるため、複数のMCPクライアントで共有可能です。Webビューアは常に http://localhost:3030 で利用可能です。

CLI

npx経由の全コマンド：

$ 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

出力例：

$ 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

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - A tier

How are these scores calculated?

Resources

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gkoreli/backlog-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server