OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List versions

list_versions

Read-onlyIdempotent

Retrieve versions, releases, milestones, and sprints to get the version IDs needed for assigning or updating work packages, and optionally scope results to a project.

Instructions

List versions (releases, milestones, sprints) you can assign work packages to.

Use it to turn "Sprint 12" or "release 2.1" into the version id that create_work_package/update_work_package need, to see which versions are still open, or to review a release plan's dates. With project_id it answers "what can I target in THIS project", which includes versions shared down from parent projects.

Returns the standard list envelope: items of {id, name, project, status, start_date, end_date, description, sharing, source} plus pagination and notes. A project-scoped listing is fetched in full, so has_more is false.

Pitfalls: project is the project that DEFINES the version, which for a shared version is not the project you asked about — assigning still works. status is open/locked/closed and OpenProject refuses to put work packages into a closed version. The instance-wide listing is capped at one page of 100; if more exist, pagination.has_more is true and notes says so — narrow with project_id rather than assuming you saw everything. include_sprints depends on the backlogs module: where it is not installed the versions still come back and notes explains the absence, so read notes before telling a user a project has no sprints.

Cross-references: create_version adds one, update_version moves its dates or closes it, delete_version removes it; get_project_metadata(project_id=...) returns the same versions alongside types and categories; to see what is IN a version use list_work_packages with a version filter. For standalone sprints (17.3+) use list_sprints/get_sprint.

Input Schema

Name	Required	Description	Default
`project_id`	No	Numeric project id or URL identifier to list the versions available in that project — including the ones shared into it from a parent. Omit it to list every version visible to you across the instance.
`include_sprints`	No	Also read /projects/{id}/sprints from the backlogs module and merge the rows in with source='sprint'. Requires project_id. If backlogs is not installed the versions are still returned and 'notes' says why sprints are missing — the call does not fail. Legacy backlogs versions only: on 17.3+ the endpoint serves standalone Sprint objects, which are skipped here (noted) — use list_sprints/get_sprint for those.

Output Schema

Name	Required	Description	Default
`sums`	No
`items`	No
`notes`	No
`groups`	No
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed47 schema fields changedv0.4.0Oct 24, 2026

changedOutput schema / properties / groups / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A server-side group bucket, computed over the full filtered set.",
-      "properties": {
-        "count": {
-          "default": 0,
-          "description": "Records in this group across all pages.",
-          "type": "integer"
-        },
-        "sums": {
-          "anyOf": [
-            {
-              "additionalProperties": {
-                "type": "number"
-              },
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Per-group sums when show_sums was requested."
-        },
-        "value": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Group value, e.g. a status name."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "sums": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "number"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

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

removedOutput schema / properties / groups / description

Removed value: -"Present only when group_by was requested."

removedOutput schema / properties / items / description
```
Removed value: -"The page of results."
```

removedOutput schema / properties / items / items / description

Removed value: -"One version (or backlogs sprint) as list results return it."

removedOutput schema / properties / items / items / properties / description / anyOf

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

removedOutput schema / properties / items / items / properties / description / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / description / description
```
Removed value: -"Description as markdown (raw); html is dropped."
```
addedOutput schema / properties / items / items / properties / description / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / end_date / anyOf

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

removedOutput schema / properties / items / items / properties / end_date / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / end_date / description
```
Removed value: -"ISO date (YYYY-MM-DD); the version's finish date."
```
addedOutput schema / properties / items / items / properties / end_date / type
```
Added value: +[
+  "string",
+  "null"
+]
```

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

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

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

removedOutput schema / properties / items / items / properties / id / description

Removed value: -"Version id — what update_version, delete_version and the work-package 'version' field consume."

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

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

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

removedOutput schema / properties / items / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / name / description
```
Removed value: -"Version name, e.g. 'Sprint 12' or '2.1'."
```
addedOutput schema / properties / items / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / project / 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 / items / items / properties / project / default
```
Removed value: -null
```

removedOutput schema / properties / items / items / properties / project / description

Removed value: -"The project that DEFINES the version. A version shared from a parent project shows that parent here, not the project you asked about."

removedOutput schema / properties / items / items / properties / sharing / anyOf

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

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

removedOutput schema / properties / items / items / properties / sharing / description

Removed value: -"How far the version is shared: none, descendants, hierarchy, tree, system."

addedOutput schema / properties / items / items / properties / sharing / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / source / default
```
Removed value: -"version"
```

removedOutput schema / properties / items / items / properties / source / description

Removed value: -"'sprint' when the row came from the backlogs sprints endpoint, 'version' otherwise. Sprints ARE versions upstream, so a row can be both and is then reported as 'sprint'."

removedOutput schema / properties / items / items / properties / start_date / anyOf

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

removedOutput schema / properties / items / items / properties / start_date / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / start_date / description
```
Removed value: -"ISO date (YYYY-MM-DD)."
```
addedOutput schema / properties / items / items / properties / start_date / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / status / anyOf

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

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

removedOutput schema / properties / items / items / properties / status / description

Removed value: -"open, locked or closed. Locked and closed versions reject new work package assignments."

addedOutput schema / properties / items / items / properties / status / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation markers: capped aggregations, unavailable modules, …"

removedOutput schema / properties / pagination / description
```
Removed value: -"Total/page/page_size/has_more."
```
removedOutput schema / properties / pagination / properties / has_more / description
```
Removed value: -"True when further pages exist."
```
removedOutput schema / properties / pagination / properties / page / description
```
Removed value: -"1-based page number of this result."
```
removedOutput schema / properties / pagination / properties / page_size / description
```
Removed value: -"Records requested per page."
```
removedOutput schema / properties / pagination / properties / total / description
```
Removed value: -"Total matching records on the server."
```
removedOutput schema / properties / sums / default
```
Removed value: -null
```

removedOutput schema / properties / sums / description

Removed value: -"Present only when show_sums was requested."

Changed1 schema field changedv0.3.3Oct 3, 2026

changedInput schema / properties / include_sprints / description

Previous value: -"Also read /projects/{id}/sprints from the backlogs module and merge the rows in with source='sprint'. Requires project_id. If backlogs is not installed the versions are still returned and 'notes' says why sprints are missing — the call does not fail."New value: +"Also read /projects/{id}/sprints from the backlogs module and merge the rows in with source='sprint'. Requires project_id. If backlogs is not installed the versions are still returned and 'notes' says why sprints are missing — the call does not fail. Legacy backlogs versions only: on 17.3+ the endpoint serves standalone Sprint objects, which are skipped here (noted) — use list_sprints/get_sprint for those."

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?

Annotations already declare a safe read, but the description goes well beyond: the 100-item page cap, has_more/notes signalling, the fact that project-scoped listings are fetched in full, that closed versions reject assignment, and that backlogs absence degrades gracefully rather than failing. These are exactly the non-obvious traits an agent needs.

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 purpose and use cases, then return shape, pitfalls, and cross-references in clearly labelled blocks. It is long, and the include_sprints/backlogs caveat appears in both description and schema, but nearly every sentence carries operational information.

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?

Even though an output schema exists, the description summarizes the envelope shape and warns about the has_more cap, and it covers the backlogs-module edge case and shared-version ownership semantics. Nothing material is missing for correct invocation or interpretation of results.

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 baseline is 3; the description still adds interpretive value by framing project_id as 'what can I target in THIS project' including versions shared from parent projects, and by flagging that include_sprints requires project_id. Some of the include_sprints text restates the schema description, keeping it from a 5.

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 and resource ('List versions (releases, milestones, sprints)') plus the crucial scope qualifier 'you can assign work packages to'. It explicitly distinguishes itself from list_sprints, get_project_metadata, and list_work_packages, 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 three concrete use cases (resolve name→id for create/update_work_package, find open versions, review release dates) and names the alternative for each adjacent need (list_sprints/get_sprint for standalone sprints, get_project_metadata for a combined view, list_work_packages for contents). Pitfalls add when-not guidance (don't assume completeness on instance-wide listing; narrow with project_id).

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

Deploy Server