OpenProject CE MCP

Overview Schema Source Related Servers Discussions Admin

list_time_entries

Read-onlyIdempotent

List and filter OpenProject time entries by project, work package, user, or date range; supports paging and optional total-hours summation.

Instructions

List time entries with optional project, work package, user, and date filters.

total is only the count of allowed time entries returned on THIS page, not a full count of all matches; the search stops as soon as it has enough, so an exact total would need an extra full walk. Page until next_offset is null.

include_total_hours=true sums hours (as an ISO 8601 duration) across every matching entry, independent of limit/offset; this runs its own full walk of the filtered collection (bounded; see total_hours_truncated), since OpenProject has no server-side sum for time entries (unlike list_work_packages's include_sums). Leave false unless the total is actually needed: it costs extra requests on top of the page this call already returns.

Input Schema

Name	Required	Description
`user`	No
`limit`	No	Page size, capped at OPENPROJECT_MAX_PAGE_SIZE.
`offset`	No	1-based page number; pass the previous result's next_offset.
`select`	No	Fields to return; a requested unset field comes back as null. Allowed: activity, comment, comment_length, comment_truncated, created_at, end_time, entity_id, entity_name, entity_type, hours, id, ongoing, project, spent_on, start_time, updated_at, user, user_id.
`project`	No	Project identifier, id, or name; a unique part of a name or identifier also matches.
`spent_on_to`	No
`spent_on_from`	No
`work_package_id`	No	Work package id (e.g. 952) or display id (e.g. "PROJ-51"), not the bare number 51.
`include_total_hours`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.4Oct 28, 2026
Removedv0.4.0Sep 12, 2026
Changed1 schema field changedv0.3.7Aug 19, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
Addedv0.3.3Jul 29, 2026
Removedv0.3.0Jul 18, 2026

Changed1 schema field changedv0.2.3Jul 9, 2026

changedOutput schema / (root)

Previous value: -{
-  "$defs": {
-    "TimeEntrySummary": {
-      "properties": {
-        "activity": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Activity"
-        },
-        "comment": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Comment"
-        },
-        "created_at": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Created At"
-        },
-        "end_time": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "End Time"
-        },
-        "entity_id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Entity Id"
-        },
-        "entity_name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Entity Name"
-        },
-        "entity_type": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Entity Type"
-        },
-        "hours": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Hours"
-        },
-        "id": {
-          "title": "Id",
-          "type": "integer"
-        },
-        "ongoing": {
-          "title": "Ongoing",
-          "type": "boolean"
-        },
-        "project": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Project"
-        },
-        "spent_on": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Spent On"
-        },
-        "start_time": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Start Time"
-        },
-        "updated_at": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Updated At"
-        },
-        "url": {
-          "title": "Url",
-          "type": "string"
-        },
-        "user": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "User"
-        }
-      },
-      "required": [
-        "id",
-        "project",
-        "entity_type",
-        "entity_id",
-        "entity_name",
-        "user",
-        "activity",
-        "hours",
-        "spent_on",
-        "start_time",
-        "end_time",
-        "ongoing",
-        "comment",
-        "created_at",
-        "updated_at",
-        "url"
-      ],
-      "title": "TimeEntrySummary",
-      "type": "object"
-    }
-  },
-  "properties": {
-    "count": {
-      "title": "Count",
-      "type": "integer"
-    },
-    "limit": {
-      "title": "Limit",
-      "type": "integer"
-    },
-    "next_offset": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "title": "Next Offset"
-    },
-    "offset": {
-      "title": "Offset",
-      "type": "integer"
-    },
-    "results": {
-      "items": {
-        "$ref": "#/$defs/TimeEntrySummary"
-      },
-      "title": "Results",
-      "type": "array"
-    },
-    "total": {
-      "title": "Total",
-      "type": "integer"
-    },
-    "truncated": {
-      "title": "Truncated",
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "offset",
-    "limit",
-    "total",
-    "count",
-    "next_offset",
-    "truncated",
-    "results"
-  ],
-  "title": "TimeEntryListResult",
-  "type": "object"
-}New value: +null

First observedv0.2.2Jul 7, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it explains that total is page-scoped because the search short-circuits, that include_total_hours performs an independent bounded full walk, that results can be truncated (total_hours_truncated), and that OpenProject has no server-side sum. This is exactly the cost/behavior context an agent needs before toggling the flag.

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?

Purpose is front-loaded in the first sentence, then the caveats follow in a logical order. The prose is slightly dense (multi-line wrapping, a parenthetical aside about OpenProject's lack of server-side sums) but each sentence carries real information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 optional params, no output schema, and only partial schema coverage, the description does the heavy lifting on paging, totals, and cost trade-offs. The main remaining gap is return-shape guidance for fields outside the select enum and the filter-value formats for user and spent_on dates.

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 56%, and the description closes the biggest gap by fully specifying include_total_hours semantics and the offset/next_offset paging contract. It does not clarify the user parameter (id vs login vs name) or the accepted date format for spent_on_from/spent_on_to, which the schema also leaves bare.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource and enumerates the filter dimensions (project, work package, user, date). It implicitly distinguishes itself from list_work_packages by contrasting include_total_hours with that tool's include_sums, though it never explicitly says when to pick it over get_time_entry or execute_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete operating guidance: page until next_offset is null, and leave include_total_hours false unless a true total is actually needed because it triggers an extra full walk. Missing only routing advice versus sibling read tools for time entries.

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

Deploy Server

list_time_entries

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools