Openproject Codex Plugin

What alex13slem/openproject-codex-plugin MCP server does

The alex13slem/openproject-codex-plugin MCP server connects Codex to OpenProject through the stable API v3 surface. It is designed for both Community and Enterprise editions and does not require an OpenProject Enterprise add-on. The project is free, open source, and licensed under MIT.

Its 41 tools cover common project-management operations. Agents can list, inspect, count, create, update, archive, and delete projects; search and modify work packages; add comments; inspect activity history; and manage dates, estimates, progress, hierarchy, assignees, priorities, statuses, and versions. The server also handles attachments, work-package relations, watchers, notifications, boards, and reference data such as types and statuses.

The integration is intended for Codex CLI workflows. For example, a user can ask Codex to find work packages matching a topic and then explicitly request a comment or update. OpenProject remains responsible for permissions and the authoritative work-package state.

How it works

The alex13slem/openproject-codex-plugin MCP server runs locally and sends requests to an OpenProject instance using an API token. The token's permissions determine which projects and operations are available. Authentication can use basic mode for broad compatibility or bearer mode for OpenProject 17.2 and later.

Read tools return pagination metadata, and work-package searches accept native filter objects with fields, operators, and string values. Count tools are available when an exact total is needed without retrieving a collection. The restricted get_openproject_api tool provides GET-only access to relative paths below /api/v3; it cannot target another host.

Write tools are intended for explicit, unambiguous requests. Destructive operations are marked separately so an MCP client can request confirmation. Upload operations read only from supplied paths under configured upload directories, resolve symlinks before checking the boundary, and reject files above the requested size limit.

Setup and configuration

The alex13slem/openproject-codex-plugin MCP server requires Bun 1.3 or newer for the repository installer, Codex CLI with MCP support, and an OpenProject API token with access to the required projects. It runs natively on macOS, Linux, and Windows.

For package-based MCP clients, run:

npx -y openproject-codex-plugin

Provide these required environment variables:

• OPENPROJECT_URL: The base URL of the OpenProject instance.
• OPENPROJECT_API_TOKEN: The API token used for requests.

Optional settings include OPENPROJECT_PAGE_SIZE, which defaults to 25 and accepts values from 1 to 100; OPENPROJECT_TIMEOUT_MS, which defaults to 30,000 milliseconds; OPENPROJECT_AUTH_MODE, whose default is basic; and OPENPROJECT_ALLOWED_UPLOAD_DIRS, which controls permitted upload roots. Existing configurations may use OPENPROJECT_BASE_URL and OPENPROJECT_API_KEY as compatibility aliases.

Repository-based installation uses the included shell or PowerShell scripts after creating a private environment file. The environment file should not be committed and should be readable only by the local user. The project also includes a Codex plugin manifest and marketplace definition for installations that support local plugin marketplaces.