OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List versions

list_versions

Read-onlyIdempotent

Find and list assignable versions, releases, milestones, or sprints, and get version IDs for creating or updating work packages; filter by project to target a project's available versions.

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

TableJSON 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

TableJSON Schema

Name	Required	Description
`sums`	No	Present only when show_sums was requested.
`items`	No	The page of results.
`notes`	No	Degradation markers: capped aggregations, unavailable modules, …
`groups`	No	Present only when group_by was requested.
`pagination`	Yes	Total/page/page_size/has_more.

Schema Changelog

Changes observed during successful MCP inspections.

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?

Beyond the readOnly/idempotent annotations it discloses non-obvious traits: the standard list envelope and fields, that project-scoped listings are fetched in full (has_more=false), the 100-item instance-wide cap, that closed versions reject work packages, and that include_sprints degrades gracefully when backlogs is absent. These are the pitfalls an agent would otherwise get wrong.

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, then usage, return shape, pitfalls, and cross-references in a scannable structure. It is longer than most definitions, but nearly every sentence carries actionable content, so the size is largely justified rather than padding.

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 purpose, usage, return shape, failure modes, and sibling relationships for a two-parameter read tool, even though an output schema already exists. An agent has everything needed to call it and interpret the result, including the shared-version and pagination edge cases.

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% and the schema already documents both params well, so the baseline is 3. The description still adds meaning beyond it by stressing that project_id includes versions shared from parent projects and that include_sprints requires project_id and depends on the backlogs module.

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?

Opens with a specific verb+resource and enumerates the domain objects it covers (releases, milestones, sprints) scoped to 'you can assign work packages to'. It also distinguishes itself from list_sprints/get_sprint for standalone Sprint objects and from get_project_metadata, 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 cases: resolving 'Sprint 12' into a version id for create/update_work_package, seeing open versions, reviewing a release plan. It also names alternatives and the condition that selects them (list_work_packages to see contents, get_project_metadata for a bundled view, list_sprints for 17.3+).

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

Deploy Server