OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Run a saved query

run_query

Read-onlyIdempotent

Execute a saved OpenProject query to return its current work packages in stored order and grouping, with pagination, group totals, and query definition for interpreting results.

Instructions

Run a saved view and get its work packages — the fastest way to answer with a team's own definition of "the sprint" or "our bugs".

OpenProject queries run on read: this returns the rows as they are right now, in the stored order and grouping. The result is the standard list envelope — items of compact work-package rows, pagination, plus groups when the query groups and sums when it asks for totals — with one addition: query carries the stored definition (name, project, readable filters, group_by, sort_by), so the rows can be interpreted without a second call.

Pitfalls. groups and sums are computed server-side across the entire result set, not the page in front of you — never re-add them from items. Omitting page_size keeps the query's own page size, which may be much larger than 20. override_filters replaces the stored filters instead of narrowing them, and never edits the saved query. A 422 means the filter set is invalid for this query's context (a project-scoped filter on a global query, an unknown custom field); violations names the attribute.

Cross-references: find query ids with list_queries; equivalent ad-hoc filtering lives in list_work_packages; open a single row with get_work_package.

Input Schema

Name	Required	Description
`page`	No	1-based page number. Omit to use the page the stored query starts on (the first).
`query_id`	Yes	Saved query id, from list_queries. It is the same id as in the UI's ?query_id= URL parameter.
`page_size`	No	Rows per page (max 100). Omit to keep the query's stored page size, which can be larger or smaller than this tool's usual default.
`override_filters`	No	Run the query with these filters instead of its stored ones, for this call only — e.g. [{'name': 'status', 'operator': 'o', 'values': []}] or [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. This REPLACES the stored filters (the API cannot merge), so re-state anything you want to keep; 'query.filters' in the result shows what the stored ones were.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed86 schema fields changedv0.4.0Oct 24, 2026

removedOutput schema / description

Removed value: -"A saved query's results: the standard list envelope plus what actually ran."

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 work-package row for list results."

changedOutput schema / properties / items / items / properties / assignee / 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 / assignee / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / assignee / description
```
Removed value: -"Assigned user or group."
```

removedOutput schema / properties / items / items / properties / display_id / anyOf

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

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

removedOutput schema / properties / items / items / properties / display_id / description

Removed value: -"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."

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

removedOutput schema / properties / items / items / properties / due_date / anyOf

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

removedOutput schema / properties / items / items / properties / due_date / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / due_date / description
```
Removed value: -"ISO date (YYYY-MM-DD)."
```
addedOutput schema / properties / items / items / properties / due_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: -"Work package id."
```
addedOutput schema / properties / items / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / percentage_done / anyOf
```
Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / percentage_done / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / percentage_done / description
```
Removed value: -"Progress, 0-100."
```
addedOutput schema / properties / items / items / properties / percentage_done / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / priority / 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 / priority / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / priority / description
```
Removed value: -"Priority."
```

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."
```

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"
+]
```

changedOutput schema / properties / items / items / properties / status / 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 / status / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / status / description
```
Removed value: -"Status."
```

removedOutput schema / properties / items / items / properties / subject / anyOf

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

removedOutput schema / properties / items / items / properties / subject / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / subject / description
```
Removed value: -"Subject line."
```
addedOutput schema / properties / items / items / properties / subject / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / type / 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 / type / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / type / description
```
Removed value: -"Work package type."
```

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 / query / description

Removed value: -"The stored query definition, so the rows can be interpreted."

removedOutput schema / properties / query / properties / display_sums / default
```
Removed value: -false
```

removedOutput schema / properties / query / properties / display_sums / description

Removed value: -"True when the query asks for totals; then the result 'sums' is populated."

removedOutput schema / properties / query / properties / filters / description

Removed value: -"The stored filters as readable sentences, e.g. 'Status open' or 'Assignee is (OR) Grace Hopper'. Empty when the query filters nothing."

removedOutput schema / properties / query / properties / group_by / anyOf

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

removedOutput schema / properties / query / properties / group_by / default
```
Removed value: -null
```
removedOutput schema / properties / query / properties / group_by / description
```
Removed value: -"Column the results are grouped by, when the query groups."
```
addedOutput schema / properties / query / properties / group_by / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / query / properties / id / anyOf

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

removedOutput schema / properties / query / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / query / properties / id / description
```
Removed value: -"Query id — pass it to run_query as query_id."
```
addedOutput schema / properties / query / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```

removedOutput schema / properties / query / properties / name / anyOf

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

removedOutput schema / properties / query / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / query / properties / name / description
```
Removed value: -"Query name as its author saved it."
```
addedOutput schema / properties / query / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

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

removedOutput schema / properties / query / properties / project / description

Removed value: -"Owning project, or null for a global (cross-project) query."

removedOutput schema / properties / query / properties / public / default
```
Removed value: -false
```

removedOutput schema / properties / query / properties / public / description

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

removedOutput schema / properties / query / properties / sort_by / description
```
Removed value: -"Stored sort order, e.g. ['Finish date asc']."
```
removedOutput schema / properties / query / properties / starred / default
```
Removed value: -false
```
removedOutput schema / properties / query / properties / starred / description
```
Removed value: -"True when the current user starred (favorited) it."
```

removedOutput schema / properties / query / properties / updated_at / anyOf

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

removedOutput schema / properties / query / properties / updated_at / default
```
Removed value: -null
```
removedOutput schema / properties / query / properties / updated_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / query / properties / updated_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```
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.9/5.0

Behavior5/5

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

Since annotations are sparse, this description carries a massive burden, succeeding by detailing key behaviors like server-side computation for sums/groups, how filters are replaced (not narrowed), and explaining specific API error codes like 422.

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?

The description is extremely dense and long, but it is logically structured by separating the primary function, the result structure, pitfalls, and cross-references. Every sentence provides high-value technical information rather than repeating fluff.

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?

Given the complexity of API operations (pagination, server-side grouping, filter manipulation), the description is exhaustive. It covers input behavior, output structure, constraints, and error handling without requiring external documentation.

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

Parameters5/5

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

While the schema coverage is 100%, the description adds crucial functional meaning, explaining that omitting `page_size` defaults to a potentially large stored size and detailing the destructive nature of `override_filters` (it replaces, it doesn't merge).

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 tool clearly states it runs a saved view and returns work packages based on the view's definition. It distinguishes this retrieval operation from other list/search functions (e.g., list_queries) by explaining that it executes the stored logic.

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?

The description proactively references related tools, specifically citing `list_queries` for obtaining IDs and `list_work_packages` for ad-hoc filtering, providing a clear decision path for the agent.

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

Deploy Server