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 across project-local (git repo root .bugtracker/bugs.db) or global system (~/.local/share/bug-tracker-mcp/bugs.db) scopes.

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, scope resolution, and converts internal exceptions to user-friendly ToolError responses.

• Scope Resolution (bug_tracker_mcp.scope): Automatically detects local project root by walking parent directories for .git or respects explicit directory overrides. Supports two scopes:

  • local (default): <git_root>/.bugtracker/bugs.db

  • global: $XDG_DATA_HOME/bug-tracker-mcp/bugs.db (or ~/.local/share/bug-tracker-mcp/bugs.db)

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

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

• Environment Configuration (bug_tracker_mcp.config): Reads optional environment variable overrides for custom local/global database paths.

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 storage locations by setting environment variables:

Tool Reference

bug_tracker_mcp exposes 6 tools to AI agents:

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