longterm-planner-mcp

A Model Context Protocol (MCP) server for long-term planning management in Claude Code. Track plans, tasks, goals, and progress across coding sessions with persistent SQLite storage.

Features

• Persistent Planning - SQLite database stores plans and tasks across sessions
• Task Management - Full lifecycle: backlog → ready → in_progress → review → completed
• State Machine - Enforced status transitions prevent invalid task states
• Task Dependencies - Define blocking relationships with circular dependency detection
• Plan Templates - 10 built-in templates for common project types (web apps, APIs, etc.)
• Search & Filter - Find tasks across plans by text, status, priority, dates, tags, assignee
• Task Tags - Categorize tasks with custom labels for organization
• Task Comments - Add timestamped notes and updates to tasks
• Bulk Operations - Update status, priority, tags, or delete multiple tasks at once
• Progress Tracking - Track estimated vs actual hours, completion stats
• Git Integration - Link commits to tasks via branch names or commit messages
• Export/Import - Export plans to JSON or Markdown, import from JSON
• Session Continuity - Pick up where you left off with context preservation
• Backup & Restore - Automated backups with rotation

When to Use

Worth it for:

• Multi-session projects where context is lost between conversations
• Team handoffs - persisted state others can pick up
• Complex features with many task dependencies
• Audit trail of decisions and progress

Overhead for:

• Single-session tasks (Claude Code's built-in TodoWrite is lighter)
• Solo work where you remember context
• Simple bug fixes or quick features

Roadmap

• [x] Auto-summarize progress when starting a new session
• [ ] Deeper git integration (auto-link commits to tasks)
• [ ] Session continuity prompts ("Last time you were working on X...")
• [ ] Time tracking and estimates vs actuals reporting

Installation

For Claude Code

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "planning": {
      "command": "npx",
      "args": ["-y", "longterm-planner-mcp"]
    }
  }
}

Restart Claude Code to load the server.

Standalone

npx longterm-planner-mcp

Or install globally:

npm install -g longterm-planner-mcp
longterm-planner-mcp

Usage

Once installed, Claude Code gains access to planning tools, resources, and prompts.

Quick Start

Create a plan for my current project with tasks for the authentication feature

Claude will use the MCP tools to:

1. Create a plan linked to your project
2. Add tasks for the feature
3. Track progress as you work

Example Workflow

# Start a planning session
> Let's plan the user authentication feature

# Claude creates plan and tasks via MCP tools

# Start working on a task
> I'm starting work on the login form task

# Claude marks task as in_progress

# Complete the task
> The login form is done, tests passing

# Claude moves task to completed, logs progress

Tools

Plan Management

| Tool | Description | |------|-------------| | create_plan | Create a new plan for a project | | get_plan | Get plan details by ID | | update_plan | Update plan name, description, dates | | list_plans | List all plans, optionally filter by project | | archive_plan | Archive a completed plan | | activate_plan | Activate a draft plan |

Task Management

| Tool | Description | |------|-------------| | add_task | Add a task to a plan | | update_task | Update task properties | | start_task | Begin working on a task | | complete_task | Mark task as completed | | block_task | Mark task as blocked with reason | | unblock_task | Remove blocker from task | | submit_for_review | Submit task for review | | find_tasks | Find tasks in a plan with filters | | get_blocked | Get all blocked tasks | | get_progress | Get plan progress statistics | | delete_task | Remove a task |

Templates

| Tool | Description | |------|-------------| | list_templates | List available plan templates | | create_from_template | Create a plan from a template |

Built-in templates: web-app, rest-api, cli-tool, library, bug-fix, feature, project-kickoff, sprint, release, migration

Dependencies

| Tool | Description | |------|-------------| | add_dependency | Add a dependency between tasks | | remove_dependency | Remove a dependency | | get_dependencies | Get task dependencies | | get_dependency_chain | Get full dependency chain | | check_can_start | Check if task can start |

Search & Filter

| Tool | Description | |------|-------------| | search_tasks | Search tasks with text and filters | | search_plans | Search plans by name/status | | find_overdue_tasks | Find tasks past due date | | find_upcoming_tasks | Find tasks due within N days | | get_task_summary | Get task statistics |

Export/Import

| Tool | Description | |------|-------------| | export_plan | Export plan to JSON or Markdown | | import_plan | Import plan from JSON |

Tags

| Tool | Description | |------|-------------| | add_tag | Add a tag to a task | | remove_tag | Remove a tag from a task | | set_tags | Set all tags for a task | | get_tags | Get all unique tags in a plan | | find_by_tag | Find tasks by tag |

Bulk Operations

| Tool | Description | |------|-------------| | bulk_update_status | Update status for multiple tasks | | bulk_update_priority | Update priority for multiple tasks | | bulk_set_assignee | Set assignee for multiple tasks | | bulk_add_tag | Add tag to multiple tasks | | bulk_remove_tag | Remove tag from multiple tasks | | bulk_delete | Delete multiple tasks |

Comments

| Tool | Description | |------|-------------| | add_comment | Add a comment to a task | | list_comments | List comments for a task | | update_comment | Update a comment | | delete_comment | Delete a comment | | get_recent_comments | Get recent comments in a plan |

Session

| Tool | Description | |------|-------------| | get_session_summary | Get project planning context at session start |

Example output:

Last session: 2d ago
Auth System: 5/12 (42%)
  active: Login form, OAuth setup
  blocked: DB migration
  ready: 3 task(s)
Last: Completed login validation (2d ago)

Resources

Access plan data via MCP resources:

| URI | Description | |-----|-------------| | plan://overview | Summary of all active plans | | plan://kanban/{planId} | Kanban board view of tasks | | plan://progress/{planId} | Progress statistics | | plan://blockers | All blocked tasks across plans | | plan://blockers/{planId} | Blocked tasks for a specific plan | | plan://today | Tasks to focus on today |

Prompts

Pre-built prompts for common planning scenarios:

| Prompt | Description | |--------|-------------| | plan_session | Start a focused planning session | | daily_standup | Review yesterday's progress, plan today | | weekly_review | Weekly progress review and planning | | decompose | Break down a large task into subtasks | | retrospective | Reflect on completed work | | unblock | Strategize solutions for blocked tasks | | prioritize | Re-prioritize backlog tasks | | scope_check | Evaluate if plan scope is realistic |

Data Storage

Plans are stored in SQLite at .claude/planning/plans.db within each project directory. This keeps planning data isolated per project and version-controllable if desired.

Upgrading from v0.2.9 or earlier

Previous versions stored all plans in a global database at ~/.claude/planning/plans.db. Version 0.2.10+ automatically migrates your data:

1. Update the package: Just restart Claude Code - it uses npx -y which fetches the latest version
2. Migration runs automatically: On first startup, existing plans are copied to their respective project directories
3. Global database archived: The old database is renamed to plans.db.migrated as a backup

No action required - the migration is seamless and preserves all your data.

Schema

• plans - Project plans with status, dates, context
• tasks - Tasks with status, priority, estimates, tags, assignments
• task_comments - Timestamped comments on tasks
• goals - High-level goals (hierarchical)
• objectives - Measurable objectives under goals
• milestones - Time-bound checkpoints
• dependencies - Task/goal dependencies
• blockers - Issues blocking progress
• progress_logs - Activity history
• sessions - Planning session tracking

Task States

Tasks follow a defined state machine:

                    ┌──────────┐
                    │ CANCELLED│
                    └──────────┘
                         ↑
┌────────┐    ┌───────┐  │  ┌─────────────┐    ┌────────┐    ┌───────────┐
│BACKLOG │ →  │ READY │ ─┼→ │ IN_PROGRESS │ →  │ REVIEW │ →  │ COMPLETED │
└────────┘    └───────┘  │  └─────────────┘    └────────┘    └───────────┘
                         │         ↓ ↑
                         │    ┌─────────┐
                         └────│ BLOCKED │
                              └─────────┘

Valid transitions:

• backlog → ready, cancelled
• ready → in_progress, backlog, cancelled
• in_progress → review, blocked, cancelled
• blocked → in_progress, cancelled
• review → completed, in_progress, cancelled

Git Integration

Link commits to tasks automatically:

Via Commit Message

git commit -m "Add login validation #task-abc123"

Via Branch Name

git checkout -b feature/task-abc123-login-form

The server parses task references and links commits for traceability.

Programmatic Usage

import {
  PlanningServer,
  Database,
  PlanRepository,
  TaskService
} from 'longterm-planner-mcp';

// Use the server
const server = new PlanningServer({
  dbPath: './my-plans.db'
});
await server.start();

// Or use components directly
const db = new Database('./plans.db');
const planRepo = new PlanRepository(db);
const plan = planRepo.create({
  projectPath: '/my/project',
  name: 'My Plan'
});

Configuration

Environment variables:

| Variable | Description | Default | |----------|-------------|---------| | PLANNING_DB_PATH | Database file path | .claude/planning/plans.db (in project dir) |

Development

# Clone the repo
git clone https://github.com/artpar/longterm-planner-mcp
cd longterm-planner-mcp

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run locally
npm start

Testing

# Run all tests
npm run test:run

# Watch mode
npm test

# Coverage
npm run test:coverage

Requirements

• Node.js >= 18.0.0
• Claude Code (for MCP integration)

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines and submit PRs.

Related

• Model Context Protocol - MCP specification
• Claude Code - AI coding assistant