Openproject Codex Plugin MCP Server

OpenProject for Codex

Manage OpenProject from Codex — including creating, updating, and commenting on work packages. This free, open-source integration uses API v3 and is designed to work with OpenProject Community and Enterprise editions.

Why this project

• Read and write: search, create, update, assign, and comment from Codex.
• 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

• Find projects and work packages you can access.
• Read complete work-package details.
• Create tasks with Markdown descriptions.
• Update subjects, descriptions, assignees, priorities, and statuses.
• Add Markdown comments to work packages.
• Guide Codex toward safe, explicit OpenProject write operations.

Example workflow

You:   Find checkout-related tasks in the Storefront project.
Codex: I found #142 "Handle expired checkout sessions" and
       #157 "Add payment retry telemetry".

You:   Add a comment to #142 saying the API fix is ready for review.
Codex: Added the comment to work package #142.

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:

git clone https://github.com/alex13slem/openproject-codex-plugin.git
cd openproject-codex-plugin

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:

mkdir -p ~/.codex
cp .env.example ~/.codex/openproject.env
chmod 600 ~/.codex/openproject.env

Set your OpenProject URL and API token in that file:

OPENPROJECT_URL=https://tasks.example.com
OPENPROJECT_API_TOKEN=your-api-token

Install the MCP integration:

./scripts/install.sh

Windows

From PowerShell, create the environment file:

$envDir = Join-Path $HOME ".codex"
New-Item -ItemType Directory -Force $envDir
Copy-Item .env.example (Join-Path $envDir "openproject.env")
notepad (Join-Path $envDir "openproject.env")

Set OPENPROJECT_URL and OPENPROJECT_API_TOKEN, save it, then install:

.\scripts\install.ps1

The installer passes paths as separate arguments, so repository and profile paths containing spaces work on every supported desktop OS.

Start using the plugin

Start a new Codex thread, then try prompts such as:

• Show my active OpenProject tasks.
• Find work packages mentioning the checkout flow.
• Add a progress comment to work package 123.

The first two prompts are read-only. Write tools are used only for explicit, unambiguous requests and return a direct link to the affected work package.

To keep the environment file elsewhere, pass its absolute path during installation on any desktop OS:

bun scripts/install.ts --env-file /secure/path/openproject.env

.\scripts\install.ps1 --env-file C:\secure\openproject.env

Tools

Write operations use the permissions of the API-token owner. Prefer a token with only the access you need, never commit it, and keep the environment file readable only by your user.

Codex plugin marketplace

The repository includes a plugin manifest and a marketplace definition at .agents/plugins/marketplace.json. Codex installations with plugin marketplace support can add the repository as a local marketplace. The Bun installer and its shell wrappers are the portable fallback when only MCP configuration is available.

OpenProject's MCP server compared

The official server may be preferable for centrally administered, multi-user OAuth deployments. This project is aimed at individual Codex users who want a portable integration and write-capable workflows.

Documentation

• Architecture and security boundaries
• Troubleshooting
• Roadmap
• Changelog
• Contributing

Community

• Ask setup questions and share workflows in GitHub Discussions.
• Report reproducible bugs with the bug template.
• Propose focused improvements with the feature template.

Please do not include API tokens, private instance URLs, or customer data in public posts.

Development

cd plugins/openproject
bun install --frozen-lockfile
bun run check

Generate a local coverage report with:

bun run test:coverage

The API module is covered by tests for request authentication, HAL collection handling, search filters, update payloads, and error responses. See CONTRIBUTING.md before opening a pull request.

Project layout

plugins/openproject/
├── .codex-plugin/plugin.json   # Plugin metadata
├── .mcp.json                   # MCP process definition
├── scripts/
│   ├── server.ts               # MCP tools and orchestration
│   └── openproject-api.ts      # Tested API client and payload helpers
├── skills/openproject/         # Codex workflow guidance
└── tests/                      # Bun unit tests

Planned work is tracked in the project roadmap. Contributions and well-scoped feature proposals are welcome.

Uninstall

macOS and Linux:

./scripts/uninstall.sh

Windows PowerShell:

.\scripts\uninstall.ps1

Project status

This project is community-maintained and is not affiliated with or endorsed by OpenProject GmbH or OpenAI. OpenProject is a trademark of OpenProject GmbH.

If this integration saves you time, consider starring the repository to help other OpenProject users discover it. Bug reports, tested-version reports, and focused contributions are equally valuable.

License

MIT