MS Procject

Control Microsoft Project via COM automation through the Model Context Protocol (MCP).

Prerequisites

• Windows with Microsoft Project installed (tested on MS Project 16.0)
• Python 3.10+
• mcp package: pip install mcp
• pywin32 for COM: pip install pywin32
• python-dateutil (optional, for add_recurring_task): pip install python-dateutil

Quick Start

1. Start MS Project and open a project file (or the server will create one).

2. Register in your claude_desktop_config.json:

{
  "mcpServers": {
    "msproject": {
      "command": "python",
      "args": ["/path/to/msproject/server.py"]
    }
  }
}

3. Run standalone (for testing):

python server.py

Tool Inventory (99 tools)

Project Management (7)

Tool	Description
open_project	Open an existing .mpp file
new_project	Create a new blank project
get_project_info	Read project metadata and summary stats
set_project_properties	Update title, manager, start date, etc.
save_project	Save current project
save_project_as	Save as .mpp or .xml
close_project	Close the active project

Task Queries (9)

Tool	Description
get_tasks	List tasks with optional filters
get_task	Get a single task by UniqueID
get_critical_path	Return critical-path tasks
get_tasks_by_rag	Filter tasks by RAG status (Text1)
get_overdue_tasks	Incomplete tasks past their finish date
get_tasks_by_resource	Tasks assigned to a named resource
search_tasks	Full-text search across task names
get_progress_summary	Dashboard: progress, RAG counts, overdue
get_wbs_structure	Hierarchical WBS tree

Task Mutations (12)

Tool	Description
update_task	Update any task field (incl. priority, task type)
bulk_update_rag	Mass RAG status update
bulk_update_tasks	Mass field updates across tasks
add_task	Add a single task
bulk_add_tasks	Add many tasks at once (JSON array)
add_recurring_task	Create recurring task occurrences (daily/weekly/monthly)
delete_task	Remove a task
set_task_mode	Toggle auto/manual scheduling
bulk_set_task_mode	Mass scheduling mode update
set_constraint	Set scheduling constraint (ASAP/ALAP/SNET/etc.)
clear_estimated_flags	Clear estimated flag on all tasks
indent_task	Indent or outdent a task

Dependencies (4)

Tool	Description
add_predecessor	Create FS/SS/FF/SF link with optional lag
bulk_add_predecessors	Mass predecessor creation
remove_predecessor	Delete a dependency link
get_task_dependencies	Show predecessors and successors

Resources (7)

Tool	Description
get_resources	List all resources in the pool
add_resource	Add a work/material/cost resource
assign_resource	Assign a resource to a task
update_resource	Modify resource properties
delete_resource	Remove a resource (clears assignments)
set_resource_calendar	Assign a specific calendar to a resource
get_resource_availability	Allocation vs capacity per period

Resource Assignments (3)

Tool	Description
bulk_assign_resources	Mass resource assignment
remove_resource_assignment	Unassign a resource from a task
get_resource_workload	Workload and conflict detection for a resource

Resource Rate Tables (2)

Tool	Description
get_resource_rate_tables	Read cost rate tables A-E for a resource
set_resource_rate_table	Set or add rate entries in a cost rate table

Custom Fields (3)

Tool	Description
rename_custom_fields	Rename Text1-Text30, Number1-Number20, etc.
update_custom_fields	Set custom field values on a task
get_custom_field_values	Read all values of a custom field

Import / Export (6)

Tool	Description
import_xml	Import from MS Project XML
export_xml	Export to MS Project XML
export_csv	Export tasks to CSV with column selection
snapshot_to_json	Full project snapshot as JSON
snapshot_diff	Compare two JSON snapshots — additions, deletions, changes
insert_subproject	Insert a subproject file

Calendars (7)

Tool	Description
get_calendars	List all project calendars
create_calendar	Create a new calendar (optionally copy from existing)
delete_calendar	Remove a base calendar
set_calendar_exception	Add exception dates (holidays) to a calendar
delete_calendar_exception	Remove a specific exception from a calendar
list_calendar_exceptions	List all exceptions on a calendar
set_project_calendar	Switch the project base calendar

Calendar Working Hours (1)

Tool	Description
set_working_hours	Modify working hours for a specific day of the week

Scheduling & Analysis (12)

Tool	Description
get_schedule_analysis	Critical path length, float analysis
validate_schedule	Find scheduling issues (missing links, etc.)
calculate_project	Recalculate the schedule after manual changes
get_milestone_report	Upcoming and overdue milestones
level_resources	Run MS Project resource leveling
find_available_slack	Tasks with free slack above threshold
get_constraints	Read non-default constraints on all tasks
set_task_calendar	Assign a calendar to a specific task
set_task_hyperlink	Set a hyperlink on a task
get_critical_path_sequence	Ordered critical path chain from start to finish with driving links
get_critical_tasks_for_period	Critical tasks and milestones within a date range (e.g. Q2)
what_if_delay	Simulate delaying a task — shows project impact, newly critical tasks, slack loss

Status Date & Progress Updates (2)

Tool	Description
update_project	Mark all tasks complete through a date (weekly PMO ritual)
reschedule_incomplete_work	Move remaining work to start after a given date

Timephased Data (1)

Tool	Description
get_timephased_data	Period-by-period work/cost data (for S-curves, cash flow)

Baselines & Earned Value (4)

Tool	Description
save_baseline	Save baseline (0-10)
clear_baseline	Clear a saved baseline
compare_baselines	Compare two baselines or baseline vs current
get_earned_value	BCWS, BCWP, ACWP, SPI, CPI per task

Variance & Reporting (1)

Tool	Description
get_variance_report	Schedule + cost variance per task vs a baseline

Cost & Work (2)

Tool	Description
get_cost_summary	Budget vs actual cost breakdown
get_actual_work	Actual vs remaining work hours per task

Progress Tracking (2)

Tool	Description
get_progress_by_wbs	Completion % rolled up by WBS level
get_dependency_chain	Walk predecessor/successor chains

Advanced Operations (8)

Tool	Description
set_deadline	Set deadline indicator on a task
bulk_set_deadlines	Mass deadline assignment
set_task_active	Activate/inactivate a task
dry_run_bulk_update	Preview bulk changes without applying
move_task	Reorder a task after another
copy_task_structure	Duplicate a task and its subtree
cross_project_link	Create inter-project dependency
undo_last	Undo recent operations (up to 10)

Multi-Project (3)

Tool	Description
list_projects	List all open projects
switch_project	Switch active project by name or index
apply_filter	Apply a built-in or custom filter

Filtering & Grouping (2)

Tool	Description
filter_tasks	Advanced multi-field filtering
group_tasks_by	Group tasks by any field with aggregation

Connectivity (1)

Tool	Description
health_check	Lightweight COM connectivity test — version, project status

Enriched Task Data

Every task query (get_task, get_tasks, etc.) returns a rich dict with 35+ fields including:

Field	Description
actual_start / actual_finish	When work actually began/ended
remaining_duration_days	How much work is left
total_slack_days / free_slack_days	Schedule flexibility
deadline	Soft deadline indicator
priority	Leveling priority (0–1000)
constraint_type / constraint_date	Scheduling constraint
manual	Auto vs manual scheduling
type	FixedUnits / FixedDuration / FixedWork
hyperlink / hyperlink_text	Task hyperlink

Known Limitations

• COM proxy staleness: When multiple projects are open, switching projects invalidates existing COM references. Always call switch_project before operating on a different file.
• Undo stack: undo_last supports up to 10 consecutive undos. MS Project's COM undo is less reliable than the UI's.
• File locking: Only one process can hold the COM connection. Don't open MS Project's GUI dialogs while the server is active.
• Timezone-aware dates: COM may return timezone-aware datetimes. The server normalizes these via _to_naive() for safe comparisons.
• Recurring tasks: MS Project's RecurringTaskInsert is a dialog-only COM method. The add_recurring_task tool simulates recurrence by creating individual occurrences under a summary task. Requires python-dateutil.
• Timephased data: get_timephased_data can be slow on large date ranges. Keep queries to reasonable periods (weeks/months, not years).

Tests

# Run all phases
python tests/test_new_tools.py  # 11 tests (core CRUD)
python tests/test_phase2.py     # 10 tests (resources, baselines, WBS)
python tests/test_phase3.py     # 15 tests (custom fields, calendars, scheduling)
python tests/test_phase4.py     # 23 tests (advanced ops, multi-project, filtering)
python tests/test_phase5.py     # 11 tests (bug fixes, cost/work tracking)
python tests/test_phase6.py     # 75 tests (timephased data, calendar mgmt, variance)
python tests/test_phase7.py     # 57 tests (critical path intelligence, what-if)

202 tests total across 7 test suites. All tests require MS Project to be running (they create and close temporary projects).

Architecture

Single-file server (server.py, ~5,200 lines) using the FastMCP framework. All COM calls go through get_app() / get_proj() helpers. Dates are normalized with _to_naive() and formatted with _fmt_date().

Development Phases

Phase	Tools	Focus
1–2	25	Core CRUD, dependencies, resources
3	44	Custom fields, calendars, scheduling analysis
4	65	Advanced operations, multi-project, filtering
5	79	Bug fixes, cost/work tracking
6	96	Timephased data, calendar management, resource availability, variance reporting
7	99	Critical path intelligence: ordered sequence, period filtering, what-if analysis

Contributing

See CONTRIBUTING.md for development setup, conventions, and how to submit changes.

License

This project is licensed under the MIT License — see LICENSE for details.