@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

OpenProject query

Sync

* = 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