OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List time entries

list_time_entries

Read-onlyIdempotent

Retrieve logged time entries filtered by project, user, work package, activity, or date range to answer how much time was spent and get accurate totals.

Instructions

List logged time, filtered server-side, with an optional accurate total.

Answers "how much time went into this ticket?" or "how much did the team spend on project X in June?". Filters combine with AND, so project_id + user='me' + a date range is one call.

Returns the standard list envelope: items of {id, hours, spent_on, comment, user, activity, work_package, project} plus pagination. hours is a float (1.5 = 1h30), never an ISO duration. With sum_hours=true, the envelope also carries sums.total_hours over all matches and a groups bucket per activity with its own count/sums.total_hours — both over the whole filtered set, so never add pages up yourself.

Pitfalls. Without view-all-time-entries you see only your own entries, so a small total may mean "not allowed to see" rather than "nobody booked time". work_package_id scopes to that one work package — child work packages are not included; a parent's roll-up needs a query per child. Summing stops at 2000 entries, noted in notes; narrow the range or project rather than trusting the number.

Cross-references: book time with log_time; correct with update_time_entry, remove with delete_time_entry; activity ids/names from get_project_metadata; the work package from get_work_package.

Input Schema

Name	Required	Description
`page`	No	1-based page number.
`user`	No	Whose time to list: numeric user id, or 'me'. Omit for everyone you're permitted to see.
`to_date`	No	Latest spent-on date, ISO YYYY-MM-DD, inclusive.
`fetch_all`	No	Aggregate every page into one result instead of page 1. Capped at 500 items (noted when it bites); mutually exclusive with page. sum_hours already reads every entry regardless.
`from_date`	No	Earliest spent-on date, ISO YYYY-MM-DD, inclusive; combine with to_date for a range (either bound optional).
`page_size`	No	Entries per page (max 100); the instance may clamp lower, reported in pagination.
`sum_hours`	No	Accurate total over every matching entry (not just this page), broken down per activity. One request per 100 matches, capped at 2000 (noted if hit). Leave false for rows only.
`project_id`	No	Only entries in this project (numeric id or identifier; from list_projects), including project-level entries with no work package.
`activity_id`	No	Only entries booked on this activity; ids are instance-specific, from get_project_metadata(project_id=...).
`work_package_id`	No	Only entries on this work package; ids from search_work_packages / list_work_packages.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed42 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 logged time entry, compact enough to list hundreds of."

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

removedOutput schema / properties / items / items / properties / activity / description

Removed value: -"Time-entry activity (Development, Management, …); instance-defined."

removedOutput schema / properties / items / items / properties / comment / anyOf

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

removedOutput schema / properties / items / items / properties / comment / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / comment / description
```
Removed value: -"Free-text comment as entered (raw); html is dropped."
```
addedOutput schema / properties / items / items / properties / comment / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / hours / anyOf

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

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

removedOutput schema / properties / items / items / properties / hours / description

Removed value: -"Logged duration in hours as a float (1.5 = one and a half hours), converted from OpenProject's ISO 8601 duration."

addedOutput schema / properties / items / items / properties / hours / type
```
Added value: +[
+  "number",
+  "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: -"Time entry id. Feed it to update_time_entry or delete_time_entry."

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 entry belongs to."
```

removedOutput schema / properties / items / items / properties / spent_on / anyOf

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

removedOutput schema / properties / items / items / properties / spent_on / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / spent_on / description
```
Removed value: -"The date the work was done, ISO YYYY-MM-DD."
```
addedOutput schema / properties / items / items / properties / spent_on / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / user / 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 / user / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / user / description
```
Removed value: -"User the time is booked for."
```

changedOutput schema / properties / items / items / properties / work_package / 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 / work_package / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / work_package / description
```
Removed value: -"Work package the time is booked on; null for project-level entries."
```
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."

Changed8 schema fields changedv0.3.2Sep 24, 2026

changedInput schema / properties / activity_id / description

Previous value: -"Only entries booked on this activity. Activity ids are instance-specific and come from get_project_metadata(project_id=...)."New value: +"Only entries booked on this activity; ids are instance-specific, from get_project_metadata(project_id=...)."

changedInput schema / properties / fetch_all / description

Previous value: -"Aggregate every page of rows into one result instead of returning page 1. Capped at 500 items with a note when the cap bites; mutually exclusive with page. sum_hours already reads every matching entry for its total, with or without fetch_all."New value: +"Aggregate every page into one result instead of page 1. Capped at 500 items (noted when it bites); mutually exclusive with page. sum_hours already reads every entry regardless."

changedInput schema / properties / from_date / description

Previous value: -"Earliest spent-on date, ISO YYYY-MM-DD, inclusive. Combine with to_date for a range; either bound may be omitted for an open-ended one."New value: +"Earliest spent-on date, ISO YYYY-MM-DD, inclusive; combine with to_date for a range (either bound optional)."

changedInput schema / properties / page_size / description

Previous value: -"Entries per page (max 100); the instance may clamp it lower and the returned pagination reports what actually came back."New value: +"Entries per page (max 100); the instance may clamp lower, reported in pagination."

changedInput schema / properties / project_id / description

Previous value: -"Only entries in this project (numeric id or identifier, from list_projects). Includes project-level entries that have no work package."New value: +"Only entries in this project (numeric id or identifier; from list_projects), including project-level entries with no work package."

changedInput schema / properties / sum_hours / description

Previous value: -"Compute an accurate total over EVERY matching entry (not just this page) and break it down per activity. Costs one request per 100 matches and is capped at 2000 entries — a cap hit is reported in 'notes'. Leave false when you only need rows."New value: +"Accurate total over every matching entry (not just this page), broken down per activity. One request per 100 matches, capped at 2000 (noted if hit). Leave false for rows only."

changedInput schema / properties / user / description

Previous value: -"Whose time to list: a numeric user id, or the literal 'me' for the token owner. Omit for everyone you are allowed to see — on most instances that is only your own entries unless you hold the view-all-time-entries permission."New value: +"Whose time to list: numeric user id, or 'me'. Omit for everyone you're permitted to see."

changedInput schema / properties / work_package_id / description

Previous value: -"Only entries booked on this work package. Ids come from search_work_packages / list_work_packages. The filter name differs between OpenProject versions; this tool probes the instance and uses the right one."New value: +"Only entries on this work package; ids from search_work_packages / list_work_packages."

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?

Adds substantial behavior beyond annotations: permission-limited visibility, 2000-entry summing cap, 500-item fetch_all cap, notes reporting, and child work-package exclusion. These are exactly the operational caveats an agent needs before trusting totals or page aggregation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, then organizes filters, return shape, pitfalls, and cross-references. Despite its length, every section carries operational value for a 10-parameter listing tool.

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, filtering, return envelope, aggregation behavior, permission caveats, caps, and related tools. With the output schema present, the description is more than complete enough for correct invocation.

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 per-parameter basics are already documented. The description adds valuable semantics not obvious from the schema, especially AND filter combination, 'me' usage, total-over-whole-filtered-set behavior, and that pages should not be added manually.

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 and resource ('List logged time') and immediately scopes it as filtered server-side with an optional total. The cross-references to log_time, update_time_entry, and delete_time_entry make its role distinct from sibling time-entry tools.

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 usage examples ('how much time went into this ticket?') and explains how filters combine in one call. It also names alternatives for booking, correcting, and removing time entries, so the agent knows when to use this versus siblings.

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

Deploy Server