forgeplan MCP Server

Turn OpenProject work packages into production code from any MCP client — Claude Code, Cursor, Windsurf, Continue, and more.

Prerequisites

• Node.js 18+
• git, and gh (GitHub) or glab (GitLab) CLI
• OpenProject instance with an API key

Install

npm install -g forgeplan-mcp-server

Setup

Add to your MCP client config:

{
  "mcpServers": {
    "forgeplan": {
      "command": "forgeplan-mcp"
    }
  }
}

| Client | Config file | |--------|-------------| | Claude Code | ~/.claude/settings.json or .mcp.json | | Cursor | .cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Continue | ~/.continue/config.json |

Then initialize your project:

Load the forgeplan config for this project

Config files are stored under .claude/forgeplan/ in your project root.

Usage

Talk to your AI assistant naturally — it discovers and calls forgeplan tools automatically.

Process OpenProject work package #42

Show me what work packages are ready to pick up

List all work packages in "Sprint 14"

Rollback work package #42

What PR is linked to work package #42?

Sync all in-progress work packages with their PR states

Prompts

| Prompt | Description | |--------|-------------| | process_work_package | Full autopilot — runs the entire pipeline end-to-end | | review_generation | Pause before committing to review generated code |

Tools Reference

Config & Init

| Tool | Description | |------|-------------| | forgeplan_load_config | Load and validate project configuration | | forgeplan_doctor | Run diagnostic health checks | | forgeplan_init_probe | Scan project to detect layers, tech stacks, tools, hooks | | forgeplan_init_discover_statuses | Connect to OpenProject and fetch statuses for mapping | | forgeplan_init_write_config | Write config files to .claude/forgeplan/ |

Work Packages

| Tool | Description | |------|-------------| | forgeplan_fetch_wp | Fetch work package with quality gate | | forgeplan_fetch_wp_context | Fetch full context (hierarchy, relations, comments) | | forgeplan_list_sprint | List work packages for a sprint | | forgeplan_wp_detail | Work package detail with hierarchy tree | | forgeplan_discover_queue | Find ready work packages | | forgeplan_claim_wp | Claim and start a work package | | forgeplan_update_wp_status | Update work package status | | forgeplan_post_wp_comment | Post a comment on a work package | | forgeplan_batch_fetch | Fetch multiple work packages at once |

Routing & Git

| Tool | Description | |------|-------------| | forgeplan_route_wp | Route work package to target layers | | forgeplan_derive_branch | Derive branch name per layer | | forgeplan_git_prepare_branch | Create or resume a branch | | forgeplan_git_status | Get git status for a layer | | forgeplan_git_commit_and_push | Stage, commit, and push | | forgeplan_git_create_pr | Create a pull request | | forgeplan_git_crosslink_prs | Cross-link multi-layer PRs | | forgeplan_rollback | Undo: close PRs, delete branches, revert status |

Pipeline & Sync

| Tool | Description | |------|-------------| | forgeplan_run_layer_checks | Run format, lint, test, build | | forgeplan_log_run | Append to run log | | forgeplan_finish_wp | Finish WP: update status, post summary | | forgeplan_review_pr | Check PR status and advance WP per config | | forgeplan_wp_to_pr | Find PR(s) linked to a work package | | forgeplan_pr_to_wp | Find work package linked to a PR/branch | | forgeplan_sync_status | Bulk sync all in-progress WPs with their PR states |

Breakdown

| Tool | Description | |------|-------------| | forgeplan_fetch_epic_for_breakdown | Fetch Epic with children/relations for decomposition | | forgeplan_resolve_op_metadata | Fetch available types and priorities for WP creation | | forgeplan_create_work_package | Create a child work package in OpenProject | | forgeplan_create_relation | Create a dependency relation between work packages |

Resources

| URI | Description | |-----|-------------| | forgeplan://rules/{wpType} | Generation rules for a work package type | | forgeplan://config | Current merged config | | forgeplan://log | Run summary log |

License

MIT