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