OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Get project metadata

get_project_metadata

Read-onlyIdempotent

Retrieve valid type, status, priority, version, category, and activity IDs and names for an OpenProject instance or project before creating, updating, or filtering work packages.

Instructions

List the ids and names that are actually valid on this instance.

This is the one-call answer to "what do I pass for type / status / priority / version / category / activity". Call it before any create or update, before filtering by ids, and whenever a write fails with an allowed-values error. Nothing here is hardcoded — priority ids and activity ids differ per instance.

Without project_id returns the global types, statuses, priorities and roles. With project_id the types list narrows to the ones enabled in that project and versions, categories and time_entry_activities are filled in. Every row is {id, name} plus its flags: statuses[].is_closed is the authoritative done marker (never classify by status name — it is localized), types[].is_milestone tells you the type takes a single date, and priorities[].is_default / time_entry_activities[].is_default say what you get by omitting the field.

Pitfalls: results are cached (default 300 s) — pass refresh=true after an admin change. Time-entry activities are read from the time-entry form, so if the time tracking module is off or you lack permission the list comes back empty with a note in notes rather than an error (check notes).

For the writable fields and custom fields of one project+type combination use get_work_package_schema; for project ids themselves use list_projects.

Input Schema

Name	Required	Description	Default
`refresh`	No	Bypass the metadata cache. Use it right after an administrator added a type, status, version or category; otherwise leave it false.
`project_id`	No	Numeric project id or URL identifier. Omit for the instance-global sets (types, statuses, priorities, roles) — cross-project filtering never needs an arbitrary project. Supply it to additionally get this project's types, versions, categories and time-entry activities.

Output Schema

Name	Required	Description	Default
`notes`	No
`roles`	No
`types`	No
`statuses`	No
`versions`	No
`categories`	No
`priorities`	No
`project_id`	No
`time_entry_activities`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed87 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"The ids and names that are valid here."

changedOutput schema / properties / categories / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A work-package category, defined per project.",
-      "properties": {
-        "default_assignee": {
-          "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": "User auto-assigned when this category is chosen."
-        },
-        "id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Resource id — pass this, not the name."
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Display name as this instance spells it."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "default_assignee": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": [
+                    "integer",
+                    "string",
+                    "null"
+                  ]
+                },
+                "name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "id": {
+          "type": [
+            "integer",
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / categories / default
```
Removed value: -null
```

removedOutput schema / properties / categories / description

Removed value: -"Project categories; null unless project_id was given."

removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation notes: modules off, permissions missing."

removedOutput schema / properties / priorities / description
```
Removed value: -"All priorities."
```

removedOutput schema / properties / priorities / items / description

Removed value: -"A work-package priority. Ids are instance-specific — never hardcode them."

removedOutput schema / properties / priorities / items / properties / id / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / priorities / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / priorities / items / properties / id / description
```
Removed value: -"Resource id — pass this, not the name."
```
addedOutput schema / properties / priorities / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```

removedOutput schema / properties / priorities / items / properties / is_active / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / priorities / items / properties / is_active / default
```
Removed value: -null
```
removedOutput schema / properties / priorities / items / properties / is_active / description
```
Removed value: -"False for retired priorities."
```
addedOutput schema / properties / priorities / items / properties / is_active / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```
removedOutput schema / properties / priorities / items / properties / is_default / anyOf
```
Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / priorities / items / properties / is_default / default
```
Removed value: -null
```
removedOutput schema / properties / priorities / items / properties / is_default / description
```
Removed value: -"Applied when none is given."
```
addedOutput schema / properties / priorities / items / properties / is_default / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / priorities / items / properties / name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / priorities / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / priorities / items / properties / name / description
```
Removed value: -"Display name as this instance spells it."
```
addedOutput schema / properties / priorities / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / project_id / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / project_id / default
```
Removed value: -null
```

removedOutput schema / properties / project_id / description

Removed value: -"The project this was scoped to; null for the global sets."

addedOutput schema / properties / project_id / type

Added value: +[
+  "integer",
+  "string",
+  "null"
+]

removedOutput schema / properties / roles / description
```
Removed value: -"All membership roles."
```
removedOutput schema / properties / roles / items / description
```
Removed value: -"A membership role."
```

removedOutput schema / properties / roles / items / properties / id / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / roles / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / roles / items / properties / id / description
```
Removed value: -"Resource id — pass this, not the name."
```
addedOutput schema / properties / roles / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```

removedOutput schema / properties / roles / items / properties / name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / roles / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / roles / items / properties / name / description
```
Removed value: -"Display name as this instance spells it."
```
addedOutput schema / properties / roles / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / statuses / description
```
Removed value: -"All statuses, each with is_closed."
```

removedOutput schema / properties / statuses / items / description

Removed value: -"A work-package status, with the flag that defines 'done'."

removedOutput schema / properties / statuses / items / properties / id / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / statuses / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / statuses / items / properties / id / description
```
Removed value: -"Resource id — pass this, not the name."
```
addedOutput schema / properties / statuses / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```

removedOutput schema / properties / statuses / items / properties / is_closed / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / statuses / items / properties / is_closed / default
```
Removed value: -null
```
removedOutput schema / properties / statuses / items / properties / is_closed / description
```
Removed value: -"Authoritative done/not-done flag — never classify by status name."
```
addedOutput schema / properties / statuses / items / properties / is_closed / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / statuses / items / properties / is_default / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / statuses / items / properties / is_default / default
```
Removed value: -null
```
removedOutput schema / properties / statuses / items / properties / is_default / description
```
Removed value: -"Status new work packages start in."
```
addedOutput schema / properties / statuses / items / properties / is_default / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / statuses / items / properties / name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / statuses / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / statuses / items / properties / name / description
```
Removed value: -"Display name as this instance spells it."
```
addedOutput schema / properties / statuses / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / time_entry_activities / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A time-entry activity, discovered from the time-entry form (never hardcoded).",
-      "properties": {
-        "id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Resource id — pass this, not the name."
-        },
-        "is_default": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Used when log_time omits activity."
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Display name as this instance spells it."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "id": {
+          "type": [
+            "integer",
+            "string",
+            "null"
+          ]
+        },
+        "is_default": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / time_entry_activities / default
```
Removed value: -null
```

removedOutput schema / properties / time_entry_activities / description

Removed value: -"Activities log_time accepts here; null unless project_id was given."

removedOutput schema / properties / types / description

Removed value: -"Work-package types; scoped to the project when project_id was given."

removedOutput schema / properties / types / items / description

Removed value: -"A work-package type (Task, Bug, Milestone, …).\n\nOpenProject 17.7+ collapses type *variants* into their root type: the global\nlisting returns fewer types than older versions showed, and variant-aware\ninstances fill ``own_name``/``parent`` on the variants that do appear."

removedOutput schema / properties / types / items / properties / id / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / types / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / types / items / properties / id / description
```
Removed value: -"Resource id — pass this, not the name."
```
addedOutput schema / properties / types / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```

removedOutput schema / properties / types / items / properties / is_default / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / types / items / properties / is_default / default
```
Removed value: -null
```
removedOutput schema / properties / types / items / properties / is_default / description
```
Removed value: -"Pre-selected for new work packages."
```
addedOutput schema / properties / types / items / properties / is_default / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / types / items / properties / is_milestone / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / types / items / properties / is_milestone / default
```
Removed value: -null
```
removedOutput schema / properties / types / items / properties / is_milestone / description
```
Removed value: -"Milestone types take a single 'date', not start/due."
```
addedOutput schema / properties / types / items / properties / is_milestone / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

removedOutput schema / properties / types / items / properties / name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / types / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / types / items / properties / name / description
```
Removed value: -"Display name as this instance spells it."
```
addedOutput schema / properties / types / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / types / items / properties / own_name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / types / items / properties / own_name / default
```
Removed value: -null
```

removedOutput schema / properties / types / items / properties / own_name / description

Removed value: -"Variant's own name without the parent prefix (17.7+); null elsewhere."

addedOutput schema / properties / types / items / properties / own_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / types / items / properties / parent / anyOf

Previous value: -[
-  {
-    "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"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / types / items / properties / parent / default
```
Removed value: -null
```
removedOutput schema / properties / types / items / properties / parent / description
```
Removed value: -"Parent type when this is a variant (17.7+); null elsewhere."
```

changedOutput schema / properties / versions / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A version / sprint defined in or shared with a project.",
-      "properties": {
-        "end_date": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "ISO date (YYYY-MM-DD)."
-        },
-        "id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Resource id — pass this, not the name."
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Display name as this instance spells it."
-        },
-        "sharing": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Sharing scope: none, descendants, hierarchy, tree, system."
-        },
-        "start_date": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "ISO date (YYYY-MM-DD)."
-        },
-        "status": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "open, locked or closed."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "end_date": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": [
+            "integer",
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "sharing": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "start_date": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "status": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / versions / default
```
Removed value: -null
```

removedOutput schema / properties / versions / description

Removed value: -"Project versions/sprints; null unless project_id was given."

First observedv0.1.0Aug 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses the 300 s cache and the refresh escape hatch, the conditional shape of the result depending on project_id, the per-row flag semantics (is_closed as the authoritative done marker, is_milestone, is_default), and the non-obvious failure mode where a missing module or permission yields an empty list with a note rather than an error. That last point is exactly the kind of silent-success caveat annotations cannot carry.

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

Conciseness4/5

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

Front-loaded with the purpose and the call-now instruction, then payload shape, then pitfalls, then sibling routing — a sensible order with no filler sentences. It loses a point for restating the project_id conditional that the schema description already covers, which is the one block that does not fully earn its space.

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?

Covers everything an agent needs before invoking a zero-required-parameter metadata lookup: when to call it, what the payload differs by, how to read the flags, staleness, and the silent-empty failure mode. With an output schema present the description needn't enumerate returns, so its extra detail is bonus rather than padding.

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 baseline is 3; the description earns an extra point by spelling out the conditional payload for each parameter value (global sets when project_id is omitted, project-scoped narrowing plus versions/categories/activities when supplied) and by warning that priority and activity ids differ per instance. It does not add format or syntax detail beyond the schema.

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?

The opening sentence states a specific verb and resource (list ids/names valid on this instance) and is reinforced by the concrete question it answers ("what do I pass for type / status / priority / version / category / activity"). It explicitly distinguishes itself from the two nearest siblings, get_work_package_schema and list_projects, so an agent can route correctly without opening a 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?

Gives explicit when-to-use triggers: before any create or update, before filtering by ids, and on allowed-values write errors. It also states the exclusion boundary — that this tool does not return writable/custom field schemas (use get_work_package_schema) and does not return project ids (use list_projects).

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

Deploy Server