lean-planning-mcp

🇺🇸 English · 🇧🇷 Versão em português

Model Context Protocol (MCP) server that exposes project schedules — Microsoft Project, Primavera P6 and Synchro Scheduler — to LLM clients like Claude Desktop and Claude Code. Reads schedules, resources, dependencies, critical-path data, and baseline variance — and adds AWP (Advanced Work Packaging, CII) and LPS (Last Planner System, Lean) layers for work-package planning, constraints, weekly commitments and PPC tracking. All local, no cloud calls, no scheduling-tool license required.

Why

Construction, engineering, and BIM workflows live in Microsoft Project schedules. This server lets your LLM:

• Inspect a project schedule and answer questions about it (deadlines, critical path, resource overload).
• Cross-reference task data with quantities from BIM models or with cost data from Power BI dashboards.
• Generate JSON exports for downstream automation (dashboards, reports, ETL pipelines).

It's read-only by design. Project edits stay where they belong: in Microsoft Project itself.

Requirements

• Python 3.11+
• An MCP-compatible client (Claude Desktop, Claude Code, etc.)
• For .xml (MSPDI): no extra dependencies
• For every other format: the optional [mpp] extra (requires a JVM via the mpxj package)

Supported formats

Format	Extension	Requires [mpp] extra
Microsoft Project MSPDI XML	.xml	No
Microsoft Project native	.mpp, .mpx	Yes
Primavera P6 export	.xer	Yes
Primavera P6 XML (PMXML)	.pmxml, .xml*	Yes
Synchro Scheduler	.sp	Yes
Asta Powerproject	.pp	Yes

* A .xml file that is not MSPDI is automatically retried through the universal reader (mpxj), so P6 XML exports saved as .xml also load.

Synchro note: mpxj reads Synchro Scheduler .sp files up to the versions it supports; for recent Synchro 4D Pro projects, exporting XER or MS Project XML from Synchro is the most reliable path. Once loaded, all 49 tools — including the AWP and LPS layers — work identically regardless of source format, since they operate on task UIDs.

Installation

Option A — uv (recommended)

git clone https://github.com/jeffersonbim/lean-planning-mcp.git
cd lean-planning-mcp
uv sync

Option B — pip

pip install git+https://github.com/jeffersonbim/lean-planning-mcp.git

For .mpp support:

uv sync --extra mpp
# or
pip install "lean-planning-mcp[mpp] @ git+https://github.com/jeffersonbim/lean-planning-mcp.git"

Claude Desktop integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "lean-planning-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\lean-planning-mcp",
        "run",
        "lean-planning-mcp"
      ]
    }
  }
}

Restart Claude Desktop. The 49 tools become available in any conversation (14 core MS Project + 17 AWP + 18 LPS).

Tools

Tool	Purpose
load_project	Load a schedule into memory — MSPDI .xml, .mpp, P6 .xer/.pmxml, Synchro .sp, Asta .pp
open_in_ms_project	Open the loaded (or a given) project file in Microsoft Project via the OS default association
project_info	Title, author, schedule window, currency, aggregate counts
list_tasks	Filter tasks by type, criticality, name substring, top N
get_task	Full record of a single task by UID, ID, or name
list_resources	Resources, optionally filtered by type or overallocation
get_resource_assignments	Assignments for one or all resources
find_overallocated_resources	Resources flagged as overallocated
get_critical_path	Tasks on the critical path, sorted by start date
get_predecessors_successors	Dependency network for a task
get_baseline_variance	Current vs baseline date and duration comparison
get_gantt_data	Tasks formatted for Gantt-chart libraries
export_to_json	Full project export to JSON file (or inline)
generate_pbip_dashboard	Generate a Power BI Project (.pbip) and open it in Power BI Desktop

Exporting .mpp to MSPDI XML

If you don't want to install Java for the optional mpp extra, export your schedule from Microsoft Project as XML:

1. Open the .mpp file in Microsoft Project.
2. File → Save As → Save as Type → XML Format (*.xml).
3. Point load_project at the resulting .xml.

The XML format is the official Microsoft Project Data Interchange (MSPDI) schema and contains tasks, resources, assignments, predecessors, baseline, and most of the project metadata.

Example prompts

After loading a project, ask Claude:

Load the project at C:\schedules\obra-acme.xml
Give me the critical path with total duration in days.
Which resources are overallocated and by how much?
List the 5 tasks with the largest baseline variance.
Export the full project to C:\reports\obra-acme.json

Two layers, deliberately separate

AWP and LPS live in the same server but operate as independent layers on top of the same schedule. They persist to separate sidecar files (awp.json and lps.json), share no state, and neither depends on the other:

• AWP organizes scope: what gets built, where, and in which package (CWA → CWP → IWP, fed by engineering and procurement packages).
• LPS organizes commitment flow: what the crews promise week by week, what blocks them, and how reliable the planning system is.

You can use either layer alone, or both side by side on the same .mpp. They are complementary methodologies — AWP answers "is the work package ready to be released?", LPS answers "will the crew actually do it this week?" — but in this server they are operated independently, by design.

AWP — Advanced Work Packaging

Construction Industry Institute (CII RT-272 / RT-319) methodology. Breaks execution into aligned packages across engineering, procurement and field:

CWA (Construction Work Area) → CWP (Construction Work Package)
                                     ↓
                               IWP (Installation Work Package)

EWP (Engineering Work Package) ─┐
                                ├→ gate CWP readiness
PWP (Procurement Work Package) ─┘

Focus: path of construction as a planning input + constraint-free release. A CWP is only ready when its manual requirements are available, all linked EWPs are issued and all linked PWPs are delivered. IWPs can only be released to the field after a passing readiness check — the WorkFace Planning golden rule.

AWP tools

Tool	Purpose
awp_list_cwa	List Construction Work Areas
awp_upsert_cwa	Create or update a CWA
awp_list_cwp	List CWPs with task_count, total_hours, any_critical
awp_upsert_cwp	Create or update a CWP (status: planned/ready/in-progress/complete/on-hold)
awp_assign_task_to_cwp	Link a task UID to a CWP (moves it if already elsewhere)
awp_set_cwp_requirements	Set CWP requirements (materials, documents, access)
awp_upsert_ewp	Create/update an Engineering Work Package (planned/in-progress/issued)
awp_list_ewp	List EWPs, optionally by CWP
awp_upsert_pwp	Create/update a Procurement Work Package (planned/ordered/delivered)
awp_list_pwp	List PWPs, optionally by CWP
awp_readiness_check	CWP readiness: requirements + EWPs issued + PWPs delivered. Gates IWP release
awp_set_path_of_construction	Define the PoC as a planning input (construction team's decided order)
awp_path_of_construction	Return the PoC — manual order if set, else derived from schedule
awp_generate_iwps	Split a CWP into IWPs (default 500h — CII crew-week sizing; stamps discipline/crew; preserves released IWPs)
awp_release_iwp	Release an IWP to the field — blocked unless the CWP passed its readiness check
awp_update_iwp_progress	Field progress 0-100% with earned hours; 100% marks complete
awp_export_wpr	Generate a Work Package Release — self-contained JSON for field teams

LPS — Last Planner System

Lean Construction method with five planning levels — all implemented:

Master → Phase (pull plan) → Lookahead (N weeks, clears constraints)
                              → WWP (Weekly Work Plan) → Daily huddle

Core rule enforced (shielding production, Ballard 1998): only constraint-free tasks enter the Weekly Work Plan. lps_add_commitment rejects tasks with open constraints unless explicitly overridden — and the override is recorded on the commitment as a risk.

Metrics: PPC (Percent Plan Complete — promises kept), plus TA (Tasks Anticipated) and TMR (Tasks Made Ready) computed from lookahead snapshots — these measure whether the make-ready process upstream is healthy, not just last week's reliability.

LPS tools

Tool	Purpose
lps_list_phases	List project phases
lps_upsert_phase	Create or update a phase (with start/end dates)
lps_set_pull_plan	Set execution sequence (pull planning) with task UIDs
lps_get_pull_plan	Retrieve a phase's pull plan
lps_annotate_pull_plan	Record handoff + conditions of satisfaction on a pull-plan entry
lps_register_constraint	Register a constraint (material/document/labor/equipment/access/permit/…)
lps_clear_constraint	Mark a constraint as resolved
lps_list_constraints	List with filters by task, status, type
lps_lookahead	N-week horizon with ready/blocked tasks + late-constraint alerts (due_date after task start)
lps_snapshot_lookahead	Persist a lookahead snapshot — feeds TA/TMR. Call at every weekly review
lps_add_commitment	Add a commitment — blocks tasks with open constraints (override: allow_constrained)
lps_mark_complete	Close a commitment with variance_reason + optional corrective_action (PDCA)
lps_log_daily	Daily-huddle entry against a committed task (level 5)
lps_get_daily_log	Read daily-huddle entries for a week
lps_get_wwp	Read a weekly work plan
lps_workable_backlog	Ready-but-uncommitted tasks — the fallback buffer for the week
lps_reliability	TA / TMR series — health of the make-ready process
lps_ppc	Compute PPC for a single week or a series of the last N weeks

Constraint types: material, document, information, design, labor, equipment, access, permit, prerequisite, other.

Variance reasons: weather, design_change, material_delay, labor_unavailable, equipment_breakdown, rework, permit, prerequisite_incomplete, scope_change, other.

Companion skill (Claude Code, Claude Desktop, claude.ai)

The repo ships a versioned adaptive skill at skills/lean-planning/SKILL.md. It detects whether the MCP tools are available in the session:

• Operation mode (MCP present): drives the 49 tools in the correct order — AWP setup sequence, weekly LPS ritual (lookahead + snapshot, binary close-out + PPC/variance), release gates, metric interpretation.
• Advisor mode (MCP absent): pure methodology — manual PPC/TA/TMR calculation from pasted data, analysis of exported MSPDI XML, IWP sizing review, cross-layer insights. The skill announces which mode is active and falls back gracefully if the server is configured but offline.

Install — Claude Code

# Windows
xcopy /E /I skills\lean-planning %USERPROFILE%\.claude\skills\lean-planning
# macOS / Linux
cp -r skills/lean-planning ~/.claude/skills/lean-planning

Install — Claude Desktop / claude.ai

Upload dist/lean-planning-skill.zip in Settings → Capabilities → Skills. Without the MCP server the skill runs in advisor mode; in Claude Desktop with the MCP server configured it runs in full operation mode.

Sidecar storage

The .mpp/.xml file remains authoritative (read-only preserved). Next to the project file, an <name>.awp/ folder holds metadata that Microsoft Project does not represent well:

C:\schedules\
├── obra-acme.mpp              ← authoritative schedule (never modified)
└── obra-acme.awp/             ← sidecar folder, created on demand
    ├── awp.json               ← CWA / CWP / IWP / EWP / PWP + path of construction
    └── lps.json               ← phases, pull plans, constraints, WWPs, snapshots

Every write updates updated_at (ISO 8601 UTC) in the JSON.

Development

uv sync --extra dev
uv run pytest -v
uv run ruff check src tests

License

MIT — see LICENSE.