OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Search work packages

search_work_packages

Read-onlyIdempotent

Find work packages by text when you know a ticket name or description but not its ID; returns compact rows with IDs and metadata for follow-up retrieval, updates, or listing.

Instructions

Find work packages by text when you do not know their ids.

Use this first whenever a user names a ticket instead of numbering it, then feed the returned id into get_work_package, update_work_package or list_work_packages.

Returns the standard list envelope: compact rows (id, subject, type, status, priority, assignee, project, dates, progress) plus pagination with total/page/page_size/has_more.

Pitfalls: search filters, it does not rank, so a broad query returns a lot — narrow it with project_id, or switch to list_work_packages when you want structured filters (assignee, due date, version) rather than text. Attachment-content matching in 'fulltext' mode depends on instance database configuration and is reported honestly in notes.

For structured filtering use list_work_packages; for one work package's full detail (description, custom fields, children) use get_work_package.

Input Schema

Name	Required	Description	Default
`mode`	No	'quick' (default) matches subject, id, project name and type/status names — this is what the OpenProject header search runs and the right choice for 'find the ticket called X'. 'fulltext' additionally matches description text, comments and searchable custom fields; use it for 'which ticket mentions Y'.	quick
`page`	No	1-based page number.
`query`	Yes	Free text to look for. In 'quick' mode a bare number also matches a work package id, so '1234' finds #1234.
`page_size`	No	Results per page (max 100).
`project_id`	No	Restrict the search to one project: numeric id or the project identifier (the slug in the OpenProject URL). Both come from list_projects. Omit to search every project the user can see.
`status_scope`	No	Which statuses to search. Defaults to 'all' because finding closed items is usually the point of a search; pass 'open' to hide finished work. An explicit status filter is always sent, so the server's implicit open-only default never applies.	all

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed57 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 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 / 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.4/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely behavioral context beyond them: search filters but does not rank, broad queries yield volume, and fulltext attachment matching depends on instance DB configuration and is surfaced in `notes`. It also describes the return envelope, though with an output schema present that portion is partly redundant, so it stops short of a 5.

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 routing rule and organized into return shape, pitfalls, and alternatives. The final sentence restates the list_work_packages/get_work_package routing already given earlier in the pitfalls paragraph, making it slightly redundant but not wasteful.

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?

For a 6-parameter read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: when to reach for it, how to narrow, what comes back, and which sibling to use instead. No gaps remain.

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 description coverage is 100% and the schema already explains mode, query, project_id and status_scope in depth, so the baseline is 3. The description only echoes project_id as a narrowing lever and never mentions status_scope, adding little the schema does not say.

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 first sentence states a specific verb+resource+condition: 'Find work packages by text when you do not know their ids.' It immediately distinguishes itself from id-based siblings by tying 'by text' to 'not ids'. An agent can separate it from list_work_packages and get_work_package without opening any 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?

Explicit use-first rule ('Use this first whenever a user names a ticket instead of numbering it'), explicit alternatives for other jobs ('For structured filtering use list_work_packages; for one work package's full detail use get_work_package'), plus a narrowing strategy for broad queries. Nothing is left to inference.

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

Deploy Server