mcp server

MS-Procject-MCP

MCP server for controlling Microsoft Project via COM automation — 79 tools for task, resource, schedule, and baseline management

elsahafy/MS-Procject-MCPcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 25, 2026

MS Project MCP Server

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

Start MS Project and open a project file (or the server will create one).
Register in your claude_desktop_config.json:

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

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.