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

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