Tpm MCP

🚀 tpm-mcp

tpm-mcp serves as your AI - powered Technical Project Manager in a box. It's a local MCP (Model Context Protocol) server that empowers Claude to track projects, features, and tasks. With it, you can have standups with Claude, track features, break down tasks, and ship products faster.

🚀 Quick Start

tpm-mcp is a local MCP (Model Context Protocol) server that gives Claude the ability to track your projects, features, and tasks. All data stays local in a fast SQLite database. Here's a quick overview of how to start using it:

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

Or you can manually edit ~/.claude/settings.json:

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

3. (Optional) Enable TPM Agent Behavior

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

✨ Features

💻 Usage Examples

Basic Usage

Here is a simple interaction example:

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

Advanced 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)

📚 Documentation

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

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

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

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

# 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

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

You: :TPM: show me the roadmap as JSON

Claude: [Returns structured JSON data]

Migration from Legacy Trackers

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.

Citation

@software{Bhatia_TPM-MCP_A_Local_2025,
  author = {Bhatia, Urjit Singh},
  license = {MIT},
  title = {{TPM-MCP: A Local Technical Product Manager MCP Server}},
  url = {https://github.com/urjitbhatia/tpm-mcp},
  year = {2025}
}