OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Create work package

create_work_package

Create OpenProject work packages such as tasks, bugs, subtasks, and milestones with form validation that reports invalid fields and their allowed values before saving.

Instructions

Create a work package, validated through OpenProject's own form endpoint first.

Use it for new tasks, bugs, subtasks (parent_id) and milestones (date). The form pre-flight surfaces an invalid status, a missing required custom field or a disallowed type as structured violations with the allowed values, before anything is written.

Returns the created work package in full detail, including its new id, lock_version and resolved custom fields.

Pitfalls: type, status and priority take names or ids; versions, assignees and parents need numeric ids. Custom fields must exist on the schema — check get_work_package_schema when unsure.

To change it afterwards use update_work_package; to attach a file to an existing work package use upload_attachment.

Input Schema

TableJSON Schema

Name	Required	Description
`date`	No	ISO date for a milestone (used instead of start_date/due_date). Passing both is rejected locally.
`type`	Yes	Type name or id ('Task', 'Bug', 'Milestone', or 7). Unknown or ambiguous names fail listing the valid values.
`notify`	No	Email notifications for this creation.
`sprint`	No	Numeric sprint id; from list_sprints. Omit to leave unset.
`status`	No	Status name or numeric id. Omit for the type's default; don't guess.
`project`	Yes	Numeric project id or identifier (URL slug); from list_projects.
`subject`	Yes	The title; must not be blank.
`version`	No	Numeric version id; from get_project_metadata.
`assignee`	No	Numeric user id ('me' isn't accepted in writes; get_instance_info gives the current user's id).
`due_date`	No	ISO date (YYYY-MM-DD); not valid on milestones.
`priority`	No	Priority name or id ('High', 'Normal', or 8). Omit for default.
`parent_id`	No	Work package id to create this as a child of.
`start_date`	No	ISO date (YYYY-MM-DD); not valid on milestones.
`description`	No	Body text in markdown.
`responsible`	No	Numeric id of the accountable person.
`story_points`	No	Story points as a non-negative integer.
`custom_fields`	No	Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields take ids or names. Unknown keys fail listing the valid ones. get_work_package_schema shows what this project/type accepts.
`estimated_hours`	No	Estimate in hours, decimal (e.g. 7.5).
`remaining_hours`	No	Remaining work in hours, decimal.
`target_versions`	No	Target version ids. [] clears; omit to keep defaults. Multiple values need instance support. Mutually exclusive with version.
`attachment_paths`	No	Local file paths to attach (stdio transport only — the server must share your filesystem).

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	Work package id.
`date`	No	Milestone date (ISO YYYY-MM-DD); null for non-milestones.
`type`	No	Work package type.
`notes`	No	Degradation notes for this result.
`author`	No	Creating user.
`parent`	No	Parent work package.
`sprint`	No	The sprint the work package is planned in; null when unassigned.
`status`	No	Status.
`project`	No	Owning project.
`subject`	No	Subject line.
`version`	No	Legacy alias: the sole target version, or null for zero/multiple.
`assignee`	No	Assigned user or group.
`category`	No	Category.
`due_date`	No	ISO date (YYYY-MM-DD).
`priority`	No	Priority.
`available`	No	Feature availability for this WP: dev links, meetings, files.
`created_at`	No	ISO 8601 UTC timestamp.
`display_id`	No	Human-facing id as the instance renders it. Matches the numeric id unless the instance uses semantic identifiers (17.x, e.g. 'PROJ-42'); null when the instance predates it.
`start_date`	No	ISO date (YYYY-MM-DD).
`updated_at`	No	ISO 8601 UTC timestamp.
`description`	No	Description as markdown (raw); html is dropped.
`responsible`	No	Accountable user.
`spent_hours`	No	Logged time in hours.
`lock_version`	No	Optimistic-locking version; pass to update_work_package.
`story_points`	No	Story points.
`custom_fields`	No	Always a list; empty when none are set.
`project_phase`	No	Project phase this work package sits in (16.1+, only when phases are active in the project and visible to this user); details via get_project_phase.
`estimated_hours`	No	Estimate in hours.
`percentage_done`	No	Progress, 0-100.
`remaining_hours`	No	Remaining work in hours.
`target_versions`	No	All target versions; legacy instances yield zero or one.

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.3.3Oct 3, 2026

changedInput schema / properties / assignee / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / parent_id / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / priority / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / responsible / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / sprint

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Numeric sprint id; from list_sprints. Omit to leave unset."
+}

changedInput schema / properties / status / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / type / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  }
+]

removedInput schema / properties / type / type
```
Removed value: -"string"
```

changedInput schema / properties / version / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / version / description

Previous value: -"Numeric version / sprint id; from get_project_metadata."New value: +"Numeric version id; from get_project_metadata."

addedOutput schema / properties / sprint

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "description": "A reference to another resource. Canonical output shape.",
+      "properties": {
+        "id": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Resource id."
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Human-readable name."
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The sprint the work package is planned in; null when unassigned."
+}

Changed18 schema fields changedv0.3.2Sep 24, 2026

changedInput schema / properties / assignee / description

Previous value: -"Numeric user id to assign. 'me' is not accepted in writes — call get_instance_info for the current user's id."New value: +"Numeric user id ('me' isn't accepted in writes; get_instance_info gives the current user's id)."

changedInput schema / properties / attachment_paths / description

Previous value: -"Local file paths to attach. Files upload uncontainered first and are claimed by the new work package, which is the flow that works even when the author lacks edit permission. Only usable when the server shares a filesystem with you (stdio transport)."New value: +"Local file paths to attach (stdio transport only — the server must share your filesystem)."

changedInput schema / properties / custom_fields / description

Previous value: -"Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields accept option ids or option names. Unknown or ambiguous keys fail with the valid keys listed — nothing is ever silently dropped. get_work_package_schema shows what this project and type accept."New value: +"Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields take ids or names. Unknown keys fail listing the valid ones. get_work_package_schema shows what this project/type accepts."

changedInput schema / properties / date / description

Previous value: -"The single ISO date of a **milestone**. Milestones carry `date` instead of start_date/due_date; passing both shapes is rejected locally."New value: +"ISO date for a **milestone** (used instead of start_date/due_date). Passing both is rejected locally."

changedInput schema / properties / description / description

Previous value: -"Body text in markdown. Omit for an empty description."New value: +"Body text in markdown."

changedInput schema / properties / due_date / description

Previous value: -"ISO date (YYYY-MM-DD). Not valid on milestone types."New value: +"ISO date (YYYY-MM-DD); not valid on milestones."

changedInput schema / properties / estimated_hours / description

Previous value: -"Estimate in hours as a decimal (7.5 = seven and a half)."New value: +"Estimate in hours, decimal (e.g. 7.5)."

changedInput schema / properties / notify / description

Previous value: -"Send OpenProject notification emails for this creation."New value: +"Email notifications for this creation."

changedInput schema / properties / parent_id / description

Previous value: -"Create this as a child of an existing work package id."New value: +"Work package id to create this as a child of."

changedInput schema / properties / priority / description

Previous value: -"Priority name or numeric id ('High', 'Normal', or 8). Omit for the instance default; priority ids differ per instance."New value: +"Priority name or id ('High', 'Normal', or 8). Omit for default."

changedInput schema / properties / project / description

Previous value: -"Numeric project id or project identifier (URL slug). Both come from list_projects."New value: +"Numeric project id or identifier (URL slug); from list_projects."

changedInput schema / properties / remaining_hours / description

Previous value: -"Remaining work in hours as a decimal."New value: +"Remaining work in hours, decimal."

changedInput schema / properties / responsible / description

Previous value: -"Numeric user id of the accountable person."New value: +"Numeric id of the accountable person."

changedInput schema / properties / start_date / description

Previous value: -"ISO date (YYYY-MM-DD). Not valid on milestone types."New value: +"ISO date (YYYY-MM-DD); not valid on milestones."

changedInput schema / properties / status / description

Previous value: -"Status name or numeric id. Omit to take the type's default status — do not guess an id."New value: +"Status name or numeric id. Omit for the type's default; don't guess."

changedInput schema / properties / subject / description

Previous value: -"The title. Required and must not be blank."New value: +"The title; must not be blank."

changedInput schema / properties / target_versions / description

Previous value: -"Target version ids. [] clears assignments; omit to use defaults. Multiple values require instance support. Mutually exclusive with version."New value: +"Target version ids. [] clears; omit to keep defaults. Multiple values need instance support. Mutually exclusive with version."

changedInput schema / properties / type / description

Previous value: -"Work package type as a **name or numeric id** ('Task', 'Bug', 'Milestone', or 7). Names resolve against this instance's types; an unknown or ambiguous name fails with the valid values listed."New value: +"Type name or id ('Task', 'Bug', 'Milestone', or 7). Unknown or ambiguous names fail listing the valid values."

Changed4 schema fields changedv0.3.1Sep 23, 2026

addedInput schema / properties / remaining_hours

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Remaining work in hours as a decimal."
+}

addedInput schema / properties / story_points

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Story points as a non-negative integer."
+}

addedOutput schema / properties / remaining_hours

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Remaining work in hours."
+}

addedOutput schema / properties / story_points

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Story points."
+}

Changed3 schema fields changedv0.3.0Sep 14, 2026

addedInput schema / properties / target_versions

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "integer"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Target version ids. [] clears assignments; omit to use defaults. Multiple values require instance support. Mutually exclusive with version."
+}

addedOutput schema / properties / target_versions

Added value: +{
+  "description": "All target versions; legacy instances yield zero or one.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A reference to another resource. Canonical output shape.",
+    "properties": {
+      "id": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Resource id."
+      },
+      "name": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Human-readable name."
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / version / description

Previous value: -"Version / sprint."New value: +"Legacy alias: the sole target version, or null for zero/multiple."

First observedv0.1.0Aug 12, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly=false, idempotent=false, destructive=false. The description adds substantive behavior beyond that: validation runs through OpenProject's form endpoint first, invalid status/missing custom field/disallowed type surface as structured violations with allowed values before any write, and the response includes id, lock_version and resolved custom fields. It also warns which fields need numeric ids versus names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and its validation mechanism, then use-cases, then return shape, then pitfalls, then hand-offs. Four tight paragraphs for a 21-parameter tool, with no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter mutation with an output schema present, this covers purpose, the pre-flight validation contract, naming/id pitfalls, cross-tool routing, and return contents. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the per-field baseline is 3. The description adds cross-field rules the schema does not: 'type, status and priority take names or ids; versions, assignees and parents need numeric ids', plus the caveat that custom fields must already exist on the schema. That is real added meaning, not repetition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (create a work package) and immediately scopes it: new tasks, bugs, subtasks via parent_id, milestones via date. An agent can distinguish it from update_work_package and delete_work_package without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'To change it afterwards use update_work_package; to attach a file to an existing work package use upload_attachment.' It also names the pre-flight schema tool (get_work_package_schema) for the uncertain case. When-to-use and alternatives are both stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server