OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List notifications

list_notifications

Read-onlyIdempotent

Read the authenticated user's OpenProject inbox to find what needs attention, mentions, assignments, or watched-item changes; filter notifications by reason, project, and unread status.

Instructions

Read the authenticated user's OpenProject inbox.

Use this to answer "what needs my attention?", "was I mentioned anywhere?" or "what changed on the things I watch?" — it is the only tool that sees notifications, and it always reports the inbox of the token owner, never another user's.

Returns the standard list envelope: items of {id, reason, read, created_at, actor, project, resource} plus pagination with total/page/page_size/has_more. resource is the thing the notification is about — {id, type, title}, usually type='WorkPackage', so resource.id feeds straight into get_work_package or list_work_package_comments.

Pitfalls. Several changes to the same work package are aggregated into one notification, so the count is not a count of events. Reading a notification here does not mark it read — that is mark_notifications. unread_only=false can return a very long history; keep a page size that fits your reply. A notification whose project the token owner has lost access to disappears from the inbox entirely.

Cross-references: mark specific rows read with mark_notifications; clear the whole (optionally filtered) inbox with mark_all_notifications_read; open the underlying ticket with get_work_package(resource.id) and its discussion with list_work_package_comments(resource.id).

Input Schema

Name	Required	Description
`page`	No	1-based page number.
`reason`	No	Restrict to one trigger: mentioned, assigned, responsible, watched, subscribed, commented, created, processed, prioritized, scheduled, shared, reminder, dateAlert. 'mentioned' is what answers "who needs me?". dateAlert filtering is an OpenProject Enterprise feature and is rejected with an explanatory hint on Community instances.
`page_size`	No	Notifications per page (max 100); the instance may clamp it lower and the returned pagination reports what actually came back.
`project_id`	No	Numeric project id or identifier to scope the inbox to one project. Ids come from list_projects.
`unread_only`	No	true (default) returns only notifications still unread in the in-app inbox; false returns read and unread together. There is no 'read only' mode — filter the rows on read=false/true yourself if you need one.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed37 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 notification in the authenticated user's inbox."

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

removedOutput schema / properties / items / items / properties / actor / description

Removed value: -"User whose action triggered it; null for system-generated notifications such as date alerts."

removedOutput schema / properties / items / items / properties / created_at / anyOf

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

removedOutput schema / properties / items / items / properties / created_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / created_at / description
```
Removed value: -"ISO 8601 UTC timestamp of when the notification was raised."
```
addedOutput schema / properties / items / items / properties / created_at / 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: -"Notification id. Pass it in mark_notifications(ids=[...]) to mark it read."

addedOutput schema / properties / items / items / properties / id / type
```
Added value: +[
+  "integer",
+  "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: -"Project the notification belongs to; null for global ones."
```
removedOutput schema / properties / items / items / properties / read / default
```
Removed value: -false
```

removedOutput schema / properties / items / items / properties / read / description

Removed value: -"True once the notification was marked read in the in-app inbox (readIAN)."

removedOutput schema / properties / items / items / properties / reason / anyOf

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

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

removedOutput schema / properties / items / items / properties / reason / description

Removed value: -"Why it was sent: mentioned, assigned, responsible, watched, subscribed, commented, created, processed, prioritized, scheduled, shared, reminder, dateAlert."

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

changedOutput schema / properties / items / items / properties / resource / anyOf

Previous value: -[
-  {
-    "description": "What a notification is about — polymorphic, usually a work package.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Id of the notified-about resource. For type='WorkPackage' this is the work package id that get_work_package and list_work_package_comments take."
-      },
-      "title": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Subject/title of the resource as OpenProject renders it."
-      },
-      "type": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "OpenProject resource type, e.g. 'WorkPackage', 'WikiPage', 'Meeting'. Kinds this server does not map surface their API collection name instead."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "title": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "type": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

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

removedOutput schema / properties / items / items / properties / resource / description

Removed value: -"The notified-about resource: {id, type, title}. Usually a work package."

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

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: reading does not mark a notification read, multiple changes aggregate into one notification so counts aren't event counts, unread_only=false can return a very long history, and notifications for lost-access projects vanish. Only the return-envelope paragraph is redundant with the existing output schema.

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?

Well front-loaded and sectioned (purpose, return, pitfalls, cross-references) with no filler sentences. The cost is that the return-envelope paragraph restates structure the output schema already provides, making it longer than strictly necessary.

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 5-param read tool with annotations and an output schema already present, everything an agent needs to call it correctly is covered: who the inbox belongs to, aggregation caveats, pagination behavior, and the follow-up call chain from resource.id.

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, but the description still adds meaning: it warns that unread_only=false yields a long history and to keep page_size within the reply budget, and it ties resource.id to get_work_package/list_work_package_comments. `reason` and `project_id` semantics live mostly in the schema, so it stops short of 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 concrete verb and resource ("Read the authenticated user's OpenProject inbox") and immediately scopes it: it is the only tool that sees notifications and always reports the token owner's inbox, never another user's. That differentiates it cleanly from mark_notifications, mark_all_notifications_read, and the work-package readers in the sibling list.

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 concrete triggering questions ("what needs my attention?", "was I mentioned anywhere?") plus explicit routing: use mark_notifications for per-row read state, mark_all_notifications_read to clear the inbox, get_work_package(resource.id) to open the ticket. The exclusions and the hand-off chain from resource.id are spelled out rather than inferred.

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

Deploy Server