Skip to main content
Glama
@nicola5tor/openproject-timelog

@nicola5tor/openproject-timelog

by NicoLa5Tor

@nicola5tor/openproject-timelog

MCP server (Model Context Protocol) for keeping a local time log and syncing it with OpenProject (API v3). Log your work in natural language from Claude Desktop (or another MCP client), review it, and upload it to OpenProject when ready.

  • Transport: stdio

  • Local storage: ~/.openproject-timelog/entries.json

  • Config: OPENPROJECT_URL and OPENPROJECT_API_KEY environment variables

Installation

No need to install anything globally: the server runs with npx.

# probarlo directamente
npx @nicola5tor/openproject-timelog

Or install it in a project:

npm install @nicola5tor/openproject-timelog
# o
pnpm add @nicola5tor/openproject-timelog

Related MCP server: OpenProject MCP Server

Configuration in Claude Desktop

Edit the configuration file (claude_desktop_config.json) and add the server under mcpServers:

{
  "mcpServers": {
    "openproject-timelog": {
      "command": "npx",
      "args": ["-y", "@nicola5tor/openproject-timelog"],
      "env": {
        "OPENPROJECT_URL": "https://tu-openproject.example.com",
        "OPENPROJECT_API_KEY": "TU_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving.

How to get your OpenProject API key

In OpenProject: My account → Access tokens → API and generate a key. The server authenticates with Basic auth using the literal user apikey and your key as the password.

The local-only tools (log_entry, list_entries, edit_entry, assign_entry, delete_entry, clear_sent) work even if you don't configure OpenProject. The query and upload tools require OPENPROJECT_URL and OPENPROJECT_API_KEY.

Tools

Local time log

Tool

Description

log_entry

Logs a time entry. Params: description, hours, workPackageId, projectId, activityId, spentOn (default today), startTime, endTime. If there's no workPackageId, it stays pending assignment.

list_entries

Lists entries by status. Param: status = pending (default) | sent | all.

edit_entry

Edits a pending entry. Params: id* + any editable field.

assign_entry

Assigns a work package to several entries. Params: entryIds, workPackageId.

delete_entry

Deletes a pending entry. Param: id*.

clear_sent

Removes all already-sent (sent) entries from the local log.

OpenProject query

Tool

Description

get_projects

Lists projects (id, name, status).

get_work_packages

Lists tasks. Optional params: projectId, status, assignee.

get_activities

Lists time entry activities (id, name).

get_time_entries

Queries already-logged hours. Optional params: projectId, workPackageId, from, to.

Sync

Tool

Description

upload_entries

Uploads entries to OpenProject. Optional param entryIds; if omitted, uploads all pending entries with a workPackageId. Each entry needs workPackageId and activityId; missing ones are reported without being uploaded. On upload, marks the entry as sent.

* = required.

Behavior notes

  • Local ids are UUID v4. Hours are stored in decimal (1.5 = 1h30m) and converted to ISO 8601 duration (PT1H30M) on upload.

  • The projectId of an entry, if not specified, is derived from the work package on upload (an extra call to OpenProject).

  • The JSON file is written atomically (temp file + rename) and operations are serialized to prevent corruption.

  • Network / credential / permission errors are returned as readable messages in the tool response, without crashing the server.

Conversational usage examples

You: Log 2 hours of today fixing the login, task 1234. Claude: (calls log_entry with description="fix login", hours=2, workPackageId=1234)

You: Log 45 minutes of meeting for me, I'll assign the task later. Claude: (log_entry description="meeting", hours=0.75) — stays pending assignment.

You: What do I have pending to upload? Claude: (list_entries status="pending")

You: Assign task 1234 to those two meetings. Claude: (assign_entry entryIds=[...], workPackageId=1234)

You: What activities are there? Set "Development" on everything and upload it. Claude: (get_activities → edit_entry/assign for activityId → upload_entries)

You: Clean up what was already uploaded. Claude: (clear_sent)

Development

npm install      # instala deps y compila (prepare -> build)
npm run build    # compila TypeScript a dist/
npm start        # ejecuta dist/index.js

Structure:

openproject-timelog/
├── src/
│   ├── index.ts        # entry point, setup MCP y registro de tools
│   ├── store.ts        # CRUD bitácora local (JSON atómico)
│   ├── openproject.ts  # cliente API OpenProject v3
│   └── types.ts        # interfaces/types
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Available Tools

16 tools
assign_entryAsignar work package a entriesB

Asigna un workPackageId a una o varias entries pendientes (por sus ids).

Inputs: entryIds (required), workPackageId (required).

clear_sentLimpiar entries enviadasA

Borra de la bitácora local todas las entries con status 'sent'.

Inputs: no named parameters.

delete_entryBorrar una entrada pendienteC

Borra una entry con status 'pending'.

Inputs: id (required).

edit_entryEditar una entrada pendienteC

Edita campos de una entry con status 'pending'. Solo se aplican los campos indicados.

Inputs: id (required), hours, endTime, spentOn, +6 more.

get_activitiesListar actividades de time entryA

Obtiene las actividades disponibles para registrar tiempo. Las actividades son por-proyecto: si pasas workPackageId se listan las de ese contexto; si no, se usa cualquier work package accesible.

Inputs: workPackageId.

get_projectsListar proyectos de OpenProjectB

Obtiene los proyectos disponibles en OpenProject.

Inputs: no named parameters.

get_time_entriesConsultar horas registradas en OpenProjectB

Consulta time entries ya registradas en OpenProject, con filtros opcionales.

Inputs: to, from, projectId, workPackageId.

get_work_packagesListar work packages de OpenProjectB

Obtiene tareas/work packages, opcionalmente filtradas por proyecto, status o assignee.

Inputs: status, assignee, projectId.

list_entriesListar entradas de la bitácoraA

Lista las entries de la bitácora local filtrando por status, opcionalmente agrupadas.

Inputs: status, groupBy, onlyActiveProject.

log_entryRegistrar entrada en la bitácoraB

Registra una entrada de horas en la bitácora local. Si no se indica workPackageId queda pendiente de asignar (con assign_entry).

Inputs: hours (required), description (required), endTime, spentOn, +5 more.

project_createCrear proyecto localA

Crea un proyecto local (workspace) para agrupar horas. Define valores por defecto (proyecto de OpenProject, work package y actividad) que se aplican al registrar horas mientras esté activo. Si es el primer proyecto, queda activo automáticamente. Se comparte entre Claude Code y Claude Desktop.

Inputs: name (required), defaultActivityId, defaultWorkPackageId, openprojectProjectId.

project_deleteBorrar un proyecto localA

Borra un proyecto local. No borra sus entries: solo las desvincula del proyecto.

Inputs: id (required).

project_listListar proyectos localesA

Lista los proyectos locales (workspaces) y marca cuál está activo. Distinto de get_projects, que consulta los proyectos de OpenProject.

Inputs: no named parameters.

project_useActivar un proyecto localA

Marca un proyecto local como activo. Las nuevas horas (log_entry) se crean dentro de él y toman sus valores por defecto.

Inputs: id (required).

upload_entriesSubir entries a OpenProjectA

Sube a OpenProject las entries indicadas (o todas las pending con workPackageId si se omite entryIds). Cada entry necesita workPackageId y activityId.

Inputs: entryIds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Tools are mostly distinct: local entry operations, remote OpenProject reads, upload/reporting, and workspace project management occupy clear separate roles. The get_projects vs project_list pair is the only potential ambiguity, though descriptions explicitly distinguish remote projects from local workspaces.

    Naming Consistency4/5

    The majority follow a clear verb_noun snake_case pattern (get_work_packages, log_entry, upload_entries). The project_* group (project_create, project_list, project_use, project_delete) reverses the order to noun_verb, which is internally consistent but a visible deviation.

    Tool Count4/5

    16 tools is at the upper edge for a focused server, but the scope includes local entries, OpenProject synchronization, remote querying, reporting, and local workspace management. Each tool has an identifiable purpose, so none feels redundant, though the surface is slightly heavy.

    Completeness4/5

    The core local-entry lifecycle is complete: create, list, edit, delete, assign, upload, and clean up. Minor gaps such as no way to update local project defaults and no remote time-entry edit/delete are present but don't block the main log-and-upload workflow.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects Claude Desktop to your OpenProject instance, allowing you to manage projects, tasks, and time entries through natural language.
      MIT