Backlog Board with Global AI MCP Server

A minimalist backlog tracking system for developers and local AI agents. It runs as a globally installed tool, keeps a registry of projects on your machine, and gives each registered project its own SQLite backlog database.

Built with Bun + Vite + SolidJS + Tailwind CSS v4 + SQLite (bun:sqlite) + ElysiaJS.

Development

Install dependencies:

bun install

Run the API and SolidJS dashboard in watch mode:

bun run dev

Build the package:

bun run build

Install on Your Machine

This tool requires Bun.

bun --version

Install Bun if needed:

curl -fsSL https://bun.sh/install | bash

Install Backlog globally:

bun add -g @augustalex/backlog

Initialize the machine-level backlog config:

backlog init

init creates the global backlog home at ~/.backlog, writes ~/.backlog/config.json, writes global AI instructions, and prints the MCP server block to add to each AI app's global MCP configuration.

Configure AI Apps Globally

Project-local MCP configs are unreliable across current AI apps. Configure one global MCP server per app instead.

Use the JSON printed by backlog init, or add an equivalent global MCP entry:

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

After that, agents can use list_projects, get_current_project, and select_project before using ticket tools.

Add a Repository as a Project

From the repository root:

backlog add-project

Or name it explicitly:

backlog add-project --name "My App"

This registers the repository in the global project registry, creates that project's database under ~/.backlog/projects/<project-id>/backlog.db, updates AGENTS.md with backlog instructions, and adds a .agents/skills/project-backlog/SKILL.md skill when the repository already uses .agents/skills.

Useful project commands:

backlog list-projects
backlog select-project <id|name|absolute-path>

Dashboard

Start the dashboard:

backlog start

The dashboard opens at http://localhost:18284 and includes a project selector for registered projects.

MCP Tools

The global project-backlog MCP server exposes:

• list_projects() - list registered projects.
• get_current_project() - show the active project.
• select_project(identifier) - select by project id, exact name, or absolute path.
• list_tickets(status?) - list tickets, optionally filtered by status.
• get_ticket(id) - get one ticket.
• create_ticket(title, description, status?) - create a ticket.
• update_ticket(id, title?, description?, status?, priority?) - update a ticket.
• delete_ticket(id) - delete a ticket.
• list_comments(ticketId) - list ticket comments.
• create_comment(ticketId, content) - add a ticket comment.
• open_dashboard() - open the web dashboard.

Agent workflow:

1. Call get_current_project.
2. If needed, call select_project with the repository path, id, or name.
3. Work the highest-priority backlog ticket by setting it to in_progress.
4. When complete, set it to done and add a summary comment.

Data Location

Backlog stores global config and project databases in ~/.backlog by default.

For tests or custom setups, set:

BACKLOG_HOME=/path/to/backlog-home

BACKLOG_DB_PATH is still supported as an override for one-off database targeting.