alex13slem/openproject-codex-plugin

**Manage OpenProject from Codex — projects, work packages, attachments,
relations, boards, users, watchers, and notifications.** This free,
open-source integration exposes 41 focused API v3 tools and is designed to
work with OpenProject Community and Enterprise editions.
Why this project
- **Broad read and write coverage:** manage projects and work packages, upload
attachments, connect related tasks, inspect boards, and handle notifications.
- **Community Edition friendly:** it uses the generally available OpenProject
API v3 rather than requiring the OpenProject MCP Enterprise add-on.
- **Codex-native workflow:** tools and guidance are packaged together so Codex
can safely turn natural-language requests into explicit OpenProject actions.
- **Runs locally:** credentials stay in a private file on your machine, and
OpenProject remains the source of truth for permissions.
OpenProject also provides an official MCP server in Professional plans and
above. As of July 2026, that server exposes read-only tools. This community
project is a good fit when you need write operations, Codex-specific guidance,
or support for Community Edition. See the
official MCP documentation
for the current capabilities of OpenProject's server.
What it can do
- Create, inspect, update, count, archive, and delete projects.
- Search work packages with native filters, sorting, and pagination.
- Create and update tasks, dates, estimates, progress, hierarchy, assignees,
accountable users, priorities, statuses, and versions.
- Read activity history, add comments, and delete work packages.
- List, download, upload, and delete attachments with size limits.
- Create and inspect work-package relations and manage watchers.
- Find users and valid assignees, including without global user-list access.
- Read and clear notifications and inspect Kanban-style boards.
- Discover statuses, priorities, types, and project versions.
- Read otherwise unsupported API v3 resources through a restricted GET-only
escape hatch.
- Guide Codex toward safe, explicit OpenProject write operations.
Example workflow
Codex resolves the request through MCP tools, while OpenProject remains the
source of truth for permissions and work-package state.
Requirements
- Bun 1.3 or newer
- Codex CLI with MCP support
- An OpenProject API token with access to the projects you want to manage
The plugin and its local MCP server run natively on macOS, Linux, and Windows.
It uses stable OpenProject API v3 endpoints and does not require an OpenProject
Enterprise add-on. If you use Community Edition, make sure API tokens are
enabled in your instance.
Quick start
Clone the repository:
MCP clients that support npm packages can instead run the server with
npx -y openproject-codex-plugin and pass OPENPROJECT_URL and
OPENPROJECT_API_TOKEN as environment variables.
The standalone server is published under
io.github.alex13slem/openproject in the official MCP Registry. Marketplace
installations use the same API permissions and security boundaries as the
local installer.
macOS and Linux
Create a private environment file:
Set your OpenProject URL and API token in that file:
Install the MCP integration:
Windows
From PowerShell, create the environment file:
Set OPENPROJECT_URL and OPENPROJECT_API_TOKEN, save it, then install:
The installer passes paths as separate arguments, so repository and profile
paths containing spaces work on every supported desktop OS.
Optional configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| OPENPROJECT_PAGE_SIZE | 25 | Default collection page size, from 1 to 100 |
| OPENPROJECT_TIMEOUT_MS | 30000 | Request timeout, from 1 to 300 seconds |