bug_tracker_mcp

A lean, agent-first Model Context Protocol (MCP) server for tracking bugs, tasks, and context across coding sessions. Designed to give AI agents (like Claude Desktop, Antigravity, and Cursor) zero-friction persistent memory for issues discovered during development.

Overview

When pair-programming with AI agents, bugs and technical debt are frequently discovered mid-task. Without a persistent tracker, these issues get lost when context windows reset.

bug_tracker_mcp solves this with a lightweight SQLite-backed MCP server. It provides 6 fast MCP tools allowing agents to log, inspect, update, resolve, and delete bugs, all isolated per project. Every tool call requires an explicit project name (e.g. the repo name) supplied by the calling agent; the server never infers it from its own working directory, since a single long-lived MCP process can serve many different projects across a session.

Related MCP server: Telebugs MCP Server

Architecture

The system is organized into decoupled Python modules:

• FastMCP Server (bug_tracker_mcp.server): Defines stdio transport MCP tools using fastmcp.FastMCP. Handles argument validation, requires a project name on every call, and converts internal exceptions to user-friendly ToolError responses.

• Database Path Resolution (bug_tracker_mcp.scope): Resolves the path to the single shared SQLite database: $XDG_DATA_HOME/bug-tracker-mcp/bugs.db (or ~/.local/share/bug-tracker-mcp/bugs.db) by default, or $BUGTRACKER_ROOT/bugs.db if overridden.

• SQLite Storage Layer (bug_tracker_mcp.storage): Manages SQLite connections with WAL journal mode, busy timeouts, auto-migrations via user_version, and full CRUD operations. Every read and write is scoped by a project column, so bugs logged under one project are invisible to and cannot be mutated from another.

• Pydantic Models (bug_tracker_mcp.models): Strict Pydantic models (Bug, BugSummary, BugListResponse) enforcing schema and typed responses.

• Environment Configuration (bug_tracker_mcp.config): Reads an optional environment variable override for the shared database's storage directory.

Installation & Setup

Install and manage dependencies using uv:

# Clone repository
git clone https://github.com/realsidg/bug_tracker_mcp.git
cd bug_tracker_mcp

# Install dependencies and setup virtual environment
uv sync

Agent Configuration

Register bug-tracker-mcp with your agent workspace or desktop client.

Workspace .mcp.json

Add to .mcp.json in your workspace root:

{
  "mcpServers": {
    "bug-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/bug_tracker_mcp",
        "bug-tracker-mcp"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bug-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/bug_tracker_mcp",
        "bug-tracker-mcp"
      ]
    }
  }
}

Environment Variables

You can override the storage location by setting an environment variable:

Tool Reference

bug_tracker_mcp exposes 6 tools to AI agents. Every tool requires a project name identifying which project the bugs belong to — use a consistent name (e.g. the repo name) for the same project across calls, since bugs are only ever returned to callers passing the matching project.

Development & Testing

Run all quality checks:

# Run pytest test suite
uv run pytest

# Check code formatting and linting
uv run ruff check .
uv run ruff format --check .

# Run static type checker in strict mode
uv run mypy src

# Run pre-commit hooks
uv run pre-commit run --all-files