OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List saved queries

list_queries

Read-onlyIdempotent

List saved work-package views to find existing team filters and query IDs, then run a view to reproduce the exact grouping and sums users see.

Instructions

List the saved work-package views (queries) this user can open.

Use it to discover what a team already tracks — "Sprint board", "My open bugs", "Overdue in Platform" — before hand-building filters: running someone's saved view with run_query reproduces exactly what they see in the UI, including their grouping and sums.

Returns the standard list envelope: rows of {id, name, project, public, starred, updated_at} plus pagination. project is null for a global query (saved outside any project); public false means the query is private to its owner, and only the owner's queries are visible to this account.

Pitfalls. Query ids are instance-wide, not per project — never guess one, take it from here. This lists definitions only; it never runs them, so nothing here says how many work packages a query returns.

Cross-references: run one with run_query(query_id=…); build an ad-hoc query instead with list_work_packages; project ids come from list_projects.

Input Schema

Name	Required	Description
`page`	No	1-based page number.
`page_size`	No	Queries per page (max 100).
`project_id`	No	Numeric project id to list only that project's saved views. Comes from list_projects. Omit to list everything visible to the current user, global queries included. A project identifier (URL slug) is not accepted here by OpenProject — use the numeric id.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed33 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: -"Compact saved-query row."
```

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: -"Query id — pass it to run_query as query_id."
```
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: -"Query name as its author saved it."
```
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: -"Owning project, or null for a global (cross-project) query."
```
removedOutput schema / properties / items / items / properties / public / default
```
Removed value: -false
```

removedOutput schema / properties / items / items / properties / public / description

Removed value: -"True when shared with everyone who can see the project; false when private to its owner."

removedOutput schema / properties / items / items / properties / starred / default
```
Removed value: -false
```
removedOutput schema / properties / items / items / properties / starred / description
```
Removed value: -"True when the current user starred (favorited) it."
```

removedOutput schema / properties / items / items / properties / updated_at / anyOf

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

removedOutput schema / properties / items / items / properties / updated_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / updated_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / items / items / properties / updated_at / 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."

First observedv0.1.0Aug 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations it discloses visibility scope (only the owner's private queries are visible), that query ids are instance-wide and must not be guessed, and that the tool never executes queries so row counts are unknowable from it. Those are exactly the traits an agent would otherwise infer wrongly.

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, then return shape, then pitfalls and cross-references — a good structure. The paragraph enumerating envelope fields is partly redundant with the existing output schema, which keeps it from a perfect score.

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?

An output schema already covers return values, so the description is free to spend its length on selection guidance, visibility rules and id pitfalls — which it does. Nothing needed to call this tool correctly is missing.

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

Parameters3/5

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

Schema coverage is 100%, so page, page_size and project_id are already fully documented, including the URL-slug caveat. The description only reiterates that project ids come from list_projects; it adds no new semantics for these parameters.

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 ('List the saved work-package views (queries)') and scopes it to 'this user can open'. It also implicitly separates itself from run_query (executes) and list_work_packages (ad-hoc filtering), so an agent can place it among siblings without reading schemas.

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 says when to use it ('discover what a team already tracks ... before hand-building filters') and names all three alternatives with their selection conditions: run_query for execution, list_work_packages for ad-hoc queries, list_projects for project ids.

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

Deploy Server