project-mcp

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

Model Context Protocol (MCP) server that exposes Microsoft Project files 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 Microsoft Project 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 .mpp (native Microsoft Project): the optional [mpp] extra (requires a JVM via the mpxj package)

Installation

Option A — uv (recommended)

git clone https://github.com/jeffmodeler/project-mcp.git
cd project-mcp
uv sync

Option B — pip

pip install git+https://github.com/jeffmodeler/project-mcp.git

For .mpp support:

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

Claude Desktop integration

Add to your claude_desktop_config.json:

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

Restart Claude Desktop. The 35 tools become available in any conversation (13 core MS Project + 10 AWP + 12 LPS).

Tools

Tool	Purpose
load_project	Load an MSPDI .xml or .mpp file into memory
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

AWP — Advanced Work Packaging

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

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

Focus: path of construction + readiness (nothing starts in the field until materials, documents and access are available).

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_readiness_check	Check whether a CWP is ready — compares requirements vs available
awp_path_of_construction	Sequence CWPs by earliest start, with critical-task counts
awp_generate_iwps	Split a CWP into IWPs sized by labor hours
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:

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

Key metric: PPC (Percent Plan Complete) — commitments kept / commitments made.

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_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 (from open constraints)
lps_add_commitment	Add a commitment to a weekly work plan (ISO week e.g. 2026-W03)
lps_mark_complete	Close a commitment with actual_hours or variance_reason
lps_get_wwp	Read a weekly work plan
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.

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 hierarchy
    └── lps.json               ← phases, pull plans, constraints, WWPs

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.