openproject (Claude Code plugin)

Lets Claude interact with a self-hosted OpenProject instance over its API v3 — projects, work packages, time entries, comments, users, and metadata — through one stdlib-only Python CLI. No pip install, no external dependencies: just a Python 3 interpreter.

Built for a single-user, local-network install (server at http://10.2.0.2:5683).

Setup

Get an API token: OpenProject → My Account → Access tokens → API.
Put it in config.json at the plugin root:
```
{
  "url": "http://10.2.0.2:5683",
  "api_key": "opapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "default_project": null
}
```
config.json is gitignored so the token never lands in version control. Environment variables OPENPROJECT_URL / OPENPROJECT_API_KEY override the file.

Verify:

python3 skills/openproject/scripts/op.py ping

What's inside

.claude-plugin/plugin.json        plugin manifest
config.json                       server URL + API token (gitignored)
commands/                         /op-ping /op-work /op-show /op-projects
                                  /op-create /op-update /op-comment /op-time
skills/openproject/
  SKILL.md                        when/how Claude uses this; full command table
  reference/filters.md            filter & query JSON syntax
  reference/api-map.md            endpoint catalog (wrapped vs. raw)
  scripts/op.py                   the CLI (argparse dispatch)
  scripts/opclient.py             HTTP client library (HAL+JSON, paging, resolvers)
  scripts/xlsx_read.py            stdlib .xlsx reader (no openpyxl) for imports

CLI quick reference

OP=skills/openproject/scripts/op.py
python3 $OP ping
python3 $OP projects --search infra
python3 $OP wp list --assignee me --status open
python3 $OP wp show 1234
python3 $OP wp create --project "Infrastructure" --type Task --subject "..." --assignee me
python3 $OP wp update 1234 --status "In progress" --done-ratio 50
python3 $OP wp comment 1234 --text "..."
python3 $OP wp relate 1234 --to 1240 --type blocks
python3 $OP time log --wp 1234 --hours 1.5 --comment "..."
python3 $OP project create --name "New Project"
python3 $OP members add --project new-project --user jdoe --role Member
python3 $OP wp delete 1234 --yes        # destructive — guarded
python3 $OP raw GET /api/v3/statuses    # escape hatch

Import a spreadsheet

Build a whole project from an .xlsx — one parent Summary task per Category, each row a child Task. Dry run by default; add --execute to write.

# Preview (writes nothing)
python3 $OP import xlsx "Plan.xlsx" --sheet "To-Do List" --project-name "My Project"
# Commit
python3 $OP import xlsx "Plan.xlsx" --sheet "To-Do List" --project-name "My Project" \
  --identifier my-project --merge-category "Display & Technology=Display & Tech" --execute

Columns are auto-detected (Task/Category/Owner/Priority/Status/Due/Notes/#). Priority H/M/L → High/Normal/Low; Status Open/In Progress/Complete → New/In progress/Closed. Owners are matched to existing users or noted in the description. Free-text dependencies are preserved in the description (link them with wp relate).

Add --json to any command for raw HAL+JSON. Names (project/type/status/priority/ assignee) resolve to ids automatically; --assignee me and --assignee none are special. Work-package updates fetch lockVersion automatically (optimistic locking).

Safety

Full CRUD is enabled, with guards: deletes require --yes, and Claude is instructed to show an item before changing it and to confirm destructive actions with you first. The token is never printed or written into OpenProject content.

3.7 KiB Raw Blame History