tpm-mcp

tpm-mcp

Your AI-powered Technical Project Manager in a box

Have standups with Claude. Track features. Break down tasks. Ship faster.

What is this?

tpm-mcp is a local MCP (Model Context Protocol) server that gives Claude the ability to track your projects, features, and tasks. Think of it as having a dedicated TPM who:

• Remembers what you're working on across sessions
• Breaks down complex features into manageable tasks
• Tracks progress and blockers
• Gives you instant status updates

All data stays local in a fast SQLite database. No cloud. No subscriptions. Just you and your AI TPM.

Demo

You: :TPM: what's in progress?

Claude: Here's your current roadmap:

# Roadmap Summary
**Stats**: 3/8 tickets, 12/25 tasks (48% complete)

## ExampleOrg
### backend-api
Tickets: 3/5 done

- [~] **FEAT-003**: Payment Integration (high)
  Tasks: 2/4
    - [~] TASK-003-1: Stripe webhook handler
    - [ ] TASK-003-2: Invoice generation

- [ ] **FEAT-004**: Email Notifications
  Tasks: 0/3

Features

Installation

1. Clone & Install

git clone https://github.com/yourusername/tpm-mcp.git
cd tpm-mcp
uv venv && uv pip install -e .

2. Add to Claude Code

claude mcp add tpm --scope user -- uv run --directory /path/to/tpm-mcp tpm-mcp

Add to ~/.claude/settings.json:

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

3. (Optional) Enable TPM Agent Behavior

For the full experience, add the TPM agent instructions:

# Symlink to your project's .claude folder
mkdir -p .claude
ln -s /path/to/tpm-mcp/agents/tpm.md .claude/tpm.md

Then in your CLAUDE.md:

See .claude/tpm.md for project tracking workflow.

Usage

Quick Commands

Workflow Example

You: :TPM: Add user authentication to the backend project

Claude: Created ticket FEAT-005: "User Authentication" in backend-api
        Status: backlog, Priority: medium

You: Make it high priority and break it down

Claude: Updated FEAT-005 to high priority. Created tasks:
        - TASK-005-1: Design auth schema
        - TASK-005-2: Implement JWT middleware
        - TASK-005-3: Add login/logout endpoints
        - TASK-005-4: Write auth tests

You: Starting on the JWT middleware

Claude: Marked TASK-005-2 as in-progress.
        FEAT-005 is now in-progress.

You: Done with middleware, tests pass

Claude: Marked TASK-005-2 as done (1/4 tasks complete)

Tools Reference

Data Model

Organization
└── Project
    └── Ticket (feature/epic/bug)
        ├── Tasks
        └── Notes

Ticket Statuses: backlog → planned → in-progress → done | blocked

Task Statuses: pending → in-progress → done | blocked

Priorities: critical > high > medium > low

Export & Import

Export and import your project data to JSON for backup, restore, or interoperability with other tools.

Export Data

Export all your project data to JSON:

# Export to stdout
uv run tpm-json-export

# Export to file
uv run tpm-json-export -o backup.json

# Export from custom database
uv run tpm-json-export --db-path /path/to/custom.db -o backup.json

Import Data

Import data from a JSON export file to recreate your database or restore from backup:

# Validate JSON file without importing
uv run tpm-json-import --dry-run backup.json

# Import into default database
uv run tpm-json-import backup.json

# Import into custom database
uv run tpm-json-import --db-path /path/to/db.db backup.json

# Clear existing data and import
uv run tpm-json-import --clear backup.json

The JSON format includes all data: organizations, projects, tickets, tasks, notes, and task dependencies. Use cases:

• Backup & Restore: Export your data regularly, restore if database gets corrupted
• Recreate Database: Start fresh by importing from a previous export
• Export to Other Tools: Use the JSON format to migrate to other project management tools
• Sync Between Machines: Export on one machine, import on another

PDF Status Reports

Generate beautiful, shareable PDF reports from your project data.

Using the Report Skill

The tpm-report skill teaches Claude how to generate professional status reports. To enable it:

# Copy the skill to your project
cp -r /path/to/tpm-mcp/skills/tpm-report .claude/skills/

Then ask Claude:

You: Generate a project status report

Claude: [Fetches roadmap data, generates styled HTML, converts to PDF]
        PDF report saved to: Project-Status-2025-12-02.pdf

Prerequisites

• tpm-mcp: This MCP server (for roadmap_view data)
• Playwright MCP: For automatic HTML → PDF conversion

Installing Playwright MCP

# Add Playwright MCP (headless mode recommended for PDF generation)
claude mcp add playwright-headless --scope user -- npx @playwright/mcp@latest --headless

# Or with isolated mode (separate browser profile)
claude mcp add playwright-headless --scope user -- npx @playwright/mcp@latest --isolated --headless

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "playwright-headless": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
  }
}

Without Playwright, Claude will generate an HTML file you can manually print to PDF.

What's in the Report?

Manual Report Generation

If you prefer manual control, use roadmap_view with JSON format:

You: :TPM: show me the roadmap as JSON

Claude: [Returns structured JSON data]

Then use your preferred tool to format the output.

Migration from Legacy Trackers

Coming from a legacy JSON-based tracker with a different format?

uv run tpm-migrate /path/to/old-tracker

This tool converts from older JSON tracker formats. For standard export/import, use tpm-json-export and tpm-json-import above.

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/ -v

Why Local?

• Privacy: Your project data never leaves your machine
• Speed: SQLite is incredibly fast for this use case
• Reliability: No API rate limits, no outages, works offline
• Simplicity: One database file, easy to backup or sync

License

MIT - do whatever you want with it.

_{Built with vibes ✨}