Openproject Codex

---
name: openproject-codex
description: "Use the OpenProject Codex plugin to inspect and manage work in Codex through the OpenProject API."
category: ai-agents-and-harness
source_repo: hashgraph-online/awesome-codex-plugins
source_path: "plugins/varaprasadreddy9676/openproject-codex-plugin/skills/openproject-codex/SKILL.md"
source_url: https://github.com/hashgraph-online/awesome-codex-plugins/blob/HEAD/plugins/varaprasadreddy9676/openproject-codex-plugin/skills/openproject-codex/SKILL.md
---


# OpenProject Codex

Use this plugin when the user wants to work with OpenProject from Codex instead of using the OpenProject UI.

The plugin is intended to cover common project-management actions directly and then fall back to the generic authenticated API tool for any OpenProject module that is not yet represented by a dedicated MCP tool.

## Behavior

- Prefer the MCP tools from this plugin for project, team, membership, and work package operations.
- Default to the configured `OPENPROJECT_DEFAULT_PROJECT` when present, unless the user explicitly asks for another project.
- Use `openproject_connection_status` first if credentials or connectivity are uncertain.
- If configuration is missing, use `openproject_setup_connection` to capture the base URL and API token directly from chat before attempting other actions.
- Use `openproject_test_connection` or `openproject_whoami` after setup when you need a quick verification step.
- API token authentication is preferred, but UI-session authentication is supported when `OPENPROJECT_UI_USERNAME` and `OPENPROJECT_UI_PASSWORD` are configured.
- Use `openproject_list_types`, `openproject_list_statuses`, `openproject_list_priorities`, and `openproject_list_project_assignees` before write operations when a value needs to be discovered.
- Use `assignee_name`, `responsible_name`, `status_name`, `priority_name`, and `customer` on `openproject_create_work_package` and `openproject_update_work_package` when the user provides human-readable values.
- Use `openproject_list_custom_field_options` or `openproject_resolve_custom_field_option` for Customer or other list-style custom fields instead of using the browser UI.
- Use dedicated tools first for projects, users, groups, memberships, versions, categories, queries, work packages, relations, watchers, comments, documents, news, time entries, attachments, file links, boards, wiki pages, meetings, reporting, and bulk task operations.
- Prefer `openproject_my_work` for “my items” or “items assigned to me” requests.
- Prefer the query tools when the user refers to saved views or wants bulk actions across a query result set.
- Prefer the bulk tools for repeated edits instead of issuing many single-item calls one by one.
- Prefer the reporting tools for workload, overdue, burndown, and project health export requests instead of assembling ad hoc summaries by hand.
- If the user needs an OpenProject action that does not yet have a dedicated tool, use `openproject_call_api` against the relevant `/api/v3/...` endpoint instead of sending the user back to OpenProject UI.
- The official OpenProject `/mcp` endpoint is read-only, so write operations should continue to use this plugin's API tools.
- Boards, wiki pages, and meetings may use authenticated UI-backed workflows when the public API surface is incomplete; ensure the UI credential env vars are configured before relying on those tools.

## Required configuration

- `OPENPROJECT_API_TOKEN` is the preferred credential.
- `OPENPROJECT_API_TOKEN_FILE` is supported for local secret-file storage and is the recommended Codex desktop setup.
- `OPENPROJECT_BASIC_API_TOKEN` is supported as a fallback for legacy Basic auth with the `apikey` user.
- `OPENPROJECT_BASIC_API_TOKEN_FILE` is supported for the same legacy Basic-auth fallback.
- `OPENPROJECT_BASE_URL` is required.
- `OPENPROJECT_DEFAULT_PROJECT` is optional.
- `OPENPROJECT_UI_USERNAME` and `OPENPROJECT_UI_PASSWORD` are required for UI-session API fallback and the boards/wiki/meetings UI-backed tools.

The plugin can now persist this configuration locally through `openproject_setup_connection`, so the user does not have to edit `.mcp.json` manually on first use.

## Typical flow

1. Check connection status.
2. Inspect projects, users, groups, memberships, versions, categories, or work packages.
3. Create, update, relate, watch, comment on, assign, or delete work through the MCP tools.
4. Use the bulk tools when the same change must be applied to many items.
5. Use `openproject_call_api` for unsupported modules or advanced API workflows.

---

**Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/varaprasadreddy9676/openproject-codex-plugin/skills/openproject-codex/SKILL.md`