Project Tracker MCP Server

A Model Context Protocol (MCP) server for managing projects, epics, and stories. This allows AI agents (Claude, GPT-5, etc.) to interact with your project tracking system in a structured way.

Features

• Hierarchical Structure: Projects → Epics → Stories

• Issue Tracking: Bug tracking, technical debt, and project issues tied to projects

• PostgreSQL Backend: Persistent storage with relational database

• MCP Integration: Compatible with Claude Desktop, GPT agents, and other MCP clients

• Full CRUD Operations: Create, read, update, and delete for all entities

• Content Storage: Store summaries, status updates, and conversation context

• No File Clutter: AI-generated content stored in database instead of markdown files

• 40 Tools: Comprehensive API for managing all aspects of project tracking

Related MCP server: Saga MCP

Setup

1. Install Dependencies

npm install

2. Configure Database

Create a .env file based on .env.example:

cp .env.example .env

Edit .env and set your PostgreSQL connection details:

DATABASE_URL=postgresql://username:password@localhost:5432/project_tracker

3. Create Database and Run Migrations

Create the database in PostgreSQL:

CREATE DATABASE project_tracker;

Then run the migration script to create tables:

npm run build
npm run db:migrate

4. Start the Server

npm run dev

Or for production:

npm run build
npm start

Database Schema

Projects

• id: UUID (Primary Key)

• name: VARCHAR(255)

• description: TEXT

• status: VARCHAR(50) (active, on_hold, completed, archived)

• created_at: TIMESTAMP

• updated_at: TIMESTAMP

Epics

• id: UUID (Primary Key)

• project_id: UUID (Foreign Key → projects)

• name: VARCHAR(255)

• description: TEXT

• status: VARCHAR(50) (idea, planned, in_progress, completed, cancelled)

• priority: VARCHAR(50) (low, medium, high, critical)

• created_at: TIMESTAMP

• updated_at: TIMESTAMP

Stories

• id: UUID (Primary Key)

• epic_id: UUID (Foreign Key → epics)

• title: VARCHAR(255)

• description: TEXT

• status: VARCHAR(50) (todo, in_progress, review, done, blocked)

• priority: VARCHAR(50) (low, medium, high, critical)

• estimated_hours: INTEGER

• actual_hours: INTEGER

• created_at: TIMESTAMP

• updated_at: TIMESTAMP

MCP Tools Available

Project Management

• create_project: Create a new project

• list_projects: List all projects with optional status filter

• get_project: Get project details with all epics and stories

• update_project: Update project information

• delete_project: Delete a project (cascades to epics and stories)

Epic Management

• create_epic: Create a new epic in a project

• list_epics: List epics for a project

• get_epic: Get epic details with all stories

• update_epic: Update epic information

• delete_epic: Delete an epic (cascades to stories)

Story Management

• create_story: Create a new story in an epic

• list_stories: List stories for an epic

• get_story: Get story details

• update_story: Update story information

• delete_story: Delete a story

Summary Management

• create_summary: Save AI-generated summaries

• list_summaries: List summaries with filters

• get_summary: Get specific summary

• search_summaries: Full-text search

• update_summary: Update summary

• delete_summary: Remove summary

Status Update Management

• create_status_update: Track progress, blockers, achievements

• list_status_updates: List status updates with filters

• get_status_update: Get specific status update

• search_status_updates: Search status updates

• update_status_update: Update status update

• delete_status_update: Remove status update

Context Management

• create_context: Save conversation context and decisions

• list_context: List context entries with filters

• get_context: Get specific context

• search_context: Search saved context

• update_context: Update context

• delete_context: Remove context

Issue Tracking

• create_issue: Report bugs, technical debt, security issues

• list_issues: List issues with filters (severity, status, assigned_to)

• get_issue: Get specific issue details

• search_issues: Search issues by keyword

• update_issue: Update issue status, assignment, resolution

• delete_issue: Remove issue

Utility

• get_project_summary: Get a comprehensive overview of all projects

Using with AI Agents

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "project-tracker": {
      "command": "node",
      "args": ["__BASE_DIR__/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://username:password@localhost:5432/project_tracker"
      }
    }
  }
}

Other MCP Clients

Connect via stdio transport to the compiled JavaScript file.

Example Usage

Once connected, AI agents can:

Create a project called "Mobile App Redesign"
→ Creates project in database

Add an epic "User Authentication" to the Mobile App Redesign project
→ Creates epic linked to project

Create a story "Implement login form" in the User Authentication epic
→ Creates story linked to epic

Create a status update for this sprint
→ Saves status report in database instead of markdown file

Save this conversation as context
→ Preserves discussion for future reference

Show me all projects with their current status
→ Retrieves and displays all projects

Get detailed view of Mobile App Redesign project
→ Shows project with all epics and stories

Additional Documentation

• Status Updates & Context Storage Guide - Learn how to use the new content storage features

• MCP Configuration - Detailed setup for VS Code and Claude Desktop

• Examples - Code examples and usage patterns

• Setup Guide - Complete installation instructions

• Quick Start - Get running in 5 minutes

Development

Watch mode for development:

npm run watch

Then in another terminal:

npm start

Available Scripts

• npm run build - Compile TypeScript

• npm start - Run the server

• npm run dev - Build and run

• npm run watch - Watch mode for development

• npm run db:migrate - Run database migrations

• npm run db:verify - Verify database schema

• npm run db:test - Test database connection

• npm run db:diagnose - Diagnose database issues

License

MIT