Skip to main content
Glama
OpenProject MCP Server

OpenProject MCP Server

OpenProject for Codex

CI GitHub release License: MIT OpenProject API v3 GitHub stars

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.

Related MCP server: openproject-mcp

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

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.

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

OPENPROJECT_AUTH_MODE

basic

Use basic for broad compatibility or bearer for OpenProject 17.2+

OPENPROJECT_ALLOWED_UPLOAD_DIRS

Current working directory

Platform-separated directories from which upload tools may read files

Existing configurations may use OPENPROJECT_BASE_URL and OPENPROJECT_API_KEY as compatibility aliases.

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

The 41 tools form one consistent OpenProject API surface:

Area

Read tools

Write tools

Projects

list_projects, get_project, count_projects

create_project, update_project, delete_project

Work packages

search_work_packages, get_work_package, count_work_packages, list_work_package_activities

create_work_package, update_work_package, add_work_package_comment, delete_work_package

Attachments

list_work_package_attachments, get_work_package_attachment

upload_work_package_attachment, delete_work_package_attachment

Relations

list_work_package_relations, get_work_package_relation

create_work_package_relation, delete_work_package_relation

Users

get_current_user, list_users, get_user, list_available_assignees

—

Watchers

list_work_package_watchers

add_work_package_watcher, remove_work_package_watcher

Notifications

list_notifications, get_notification

mark_notification_read, mark_all_notifications_read

Boards

list_boards, get_board, list_board_lanes

—

Reference data

list_work_package_types, list_work_package_statuses, list_work_package_priorities, list_project_versions

—

Advanced

get_openproject_api

—

List tools return pagination metadata. Native filter objects use field, operator, and string values; count tools should be preferred when only a total is needed. get_openproject_api accepts only relative GET paths under /api/v3 and cannot call another host.

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. File uploads read only explicitly supplied paths under configured upload roots, resolve symlinks before enforcing that boundary, and reject files above the requested size limit. Delete operations are separately marked destructive so MCP clients can require confirmation.

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

Capability

This project

OpenProject MCP server

Community Edition

Yes

Enterprise add-on

Search and read

Yes

Yes

Create, update, comment, relate, and attach

Yes

Read-only as of July 2026

Codex workflow guidance

Included

Client-independent

Deployment

Local Bun process

Built into OpenProject

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

Community

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

Available Tools

41 tools
add_work_package_commentA

Append a Markdown comment to one work package and return the activity plus work-package URL. Use for progress notes or follow-ups, not field changes; this creates a permanent activity and can notify subscribed users.

Inputs: id (required), comment (required).

add_work_package_watcherA
Idempotent

Subscribe a user as a watcher of one work package so OpenProject can notify them about changes. Use only for an explicit subscription request; adding an existing watcher is idempotent.

Inputs: userId (required), workPackageId (required).

count_projectsA
Read-only

Return only the total number of projects matching native OpenProject filters. Use instead of list_projects when no project records are needed; this is read-only and minimizes response size.

Inputs: filters.

count_work_packagesA
Read-only

Return only the total number of work packages matching native filters and an optional project. Use instead of search_work_packages when no task records are needed; all filters are combined with AND.

Inputs: filters, projectId.

create_projectA

Create a project or subproject immediately. Use only after confirming a new project is wanted; parentId creates it below an existing project. Requires add-project permission and is not idempotent.

Inputs: name (required), public, parentId, identifier, +1 more.

create_work_packageA

Create a work package and return the created resource plus browser URL. Use only for a new task in a resolved project; this writes immediately and may notify interested users unless notify is false. Omit typeId to select the project's Task type or first available type.

Inputs: subject (required), projectId (required), notify, typeId, +10 more.

create_work_package_relationA

Create a directed typed relation from one work package to another, such as blocks, precedes, duplicates, or relates. Use after verifying both IDs and existing relations; this writes immediately and duplicate validity is enforced by OpenProject.

Inputs: toId (required), type (required), fromId (required), lag, +1 more.

delete_projectA
DestructiveIdempotent

Permanently schedule deletion of a project by numeric ID. Use only after get_project verifies an explicit deletion target. OpenProject archives it immediately and deletes it asynchronously; this destructive action cannot be undone through this server.

Inputs: id (required).

delete_work_packageA
DestructiveIdempotent

Permanently delete one work package by ID. Use only for an explicit deletion request after verifying the target with get_work_package; this is destructive and cannot be undone through this server.

Inputs: id (required).

delete_work_package_attachmentA
DestructiveIdempotent

Permanently delete one attachment by attachment ID. Use only after list_work_package_attachments verifies the file and ID; this is destructive and does not delete the work package.

Inputs: attachmentId (required).

delete_work_package_relationA
DestructiveIdempotent

Permanently delete one relation without deleting either work package. Use only after list_work_package_relations confirms the relation ID; this destructive change removes the dependency or association.

Inputs: id (required).

get_boardA
Read-only

Get one OpenProject board by grid ID, including its widget and column configuration. Use when the board ID is already known; use list_boards for project discovery or list_board_lanes for cards.

Inputs: id (required).

get_current_userA
Read-only

Return the current OpenProject user authenticated by the API token. Use to identify 'me' or verify credentials; unlike list_users, this does not require global user-management permission.

Inputs: no named parameters.

get_notificationA
Read-only

Get one in-app notification by ID with actor, project, activity, and related-resource links. Use after list_notifications when full context for a known notification is required; it remains unread.

Inputs: id (required).

get_openproject_apiA
Read-only

Read an OpenProject API v3 endpoint not covered by a focused tool. Use only as a read-only escape hatch after checking the typed tools. The path must be relative under /api/v3; absolute URLs, other origins, writes, and filesystem access are rejected.

Inputs: path (required).

get_projectA
Read-only

Get one complete project by numeric ID or identifier. Use when the target is already known and full project fields or links are needed; use list_projects for discovery. This is read-only.

Inputs: idOrIdentifier (required).

get_userA
Read-only

Get one OpenProject user by numeric ID. Use when the ID is already known; use list_available_assignees for assignment choices and list_users for administrator-level discovery.

Inputs: id (required).

get_work_packageA
Read-only

Get the complete HAL+JSON representation of one work package by numeric ID. Use after search when full descriptions, links, custom fields, or lockVersion are required; this performs no write.

Inputs: id (required).

get_work_package_attachmentA
Read-only

Download one verified attachment from a work package. Use after listing attachments. Text files return readable text; binary files return an embedded base64 MCP resource. The call fails before or during transfer if maxBytes is exceeded and does not write to disk.

Inputs: attachmentId (required), workPackageId (required), maxBytes.

get_work_package_relationA
Read-only

Get one relation by relation ID, including its from/to links, type, description, and lag. Use after listing relations when complete details for a known relation are needed.

Inputs: id (required).

list_available_assigneesA
Read-only

List users permitted as assignees for exactly one project or work package. Use this before assignment when the global user list is unavailable; provide projectId or workPackageId, never both. This is read-only.

Inputs: projectId, workPackageId.

list_board_lanesA
Read-only

Resolve one board's work-package query widgets into lanes with card summaries and pagination metadata. Use after list_boards identifies a board; pageSize limits cards per lane. This is read-only and does not move cards.

Inputs: boardId (required), pageSize.

list_boardsA
Read-only

List paginated Kanban-style boards scoped to one project ID or identifier. Use to discover board grid IDs; use get_board for configuration or list_board_lanes for cards. This read-only call may return no boards when the module is disabled.

Inputs: projectIdOrIdentifier (required), offset, pageSize.

list_notificationsA
Read-only

List paginated in-app notifications for the authenticated user, optionally unread only. Use for inbox triage; this leaves read state unchanged. Use get_notification for one item's details and mark tools only after review.

Inputs: offset, pageSize, unreadOnly.

list_projectsA
Read-only

List visible projects with native filters, sorting, and pagination. Use this to discover project IDs or identifiers; use get_project when the target is already known and count_projects when only a total is needed.

Inputs: query, offset, sortBy, filters, +1 more.

list_project_versionsA
Read-only

List version or milestone IDs globally or for one project. Use before assigning a work package to a version; projectId returns only versions available in that project. This is read-only.

Inputs: offset, pageSize, projectId.

list_usersA
Read-only

List or search the global OpenProject user directory with native filters and pagination. Use for administrator-level discovery; for ordinary task assignment prefer list_available_assignees because OpenProject may restrict this endpoint to user managers. This is read-only.

Inputs: query, offset, sortBy, filters, +1 more.

list_work_package_activitiesA
Read-only

List paginated comments and field-change history for one work package. Use for audit context or conversation history; use get_work_package for current state and add_work_package_comment to append a new note. This is read-only.

Inputs: workPackageId (required), offset, pageSize.

list_work_package_attachmentsA
Read-only

List metadata for files attached directly to a work package. Use before get_work_package_attachment to verify the attachment ID and size; no file content is downloaded.

Inputs: workPackageId (required).

list_work_package_prioritiesA
Read-only

List configured OpenProject work package priorities and their IDs. Use this read-only discovery tool before creating, filtering, or updating work packages that reference work package priorities.

Inputs: no named parameters.

list_work_package_relationsA
Read-only

List all typed relations involving one work package, including direction and lag. Use to inspect dependencies or duplicates before creating or deleting a relation; this is read-only.

Inputs: workPackageId (required).

list_work_package_statusesA
Read-only

List configured OpenProject work package statuses and their IDs. Use this read-only discovery tool before creating, filtering, or updating work packages that reference work package statuses.

Inputs: no named parameters.

list_work_package_typesA
Read-only

List configured OpenProject work package types and their IDs. Use this read-only discovery tool before creating, filtering, or updating work packages that reference work package types.

Inputs: no named parameters.

list_work_package_watchersA
Read-only

List current watchers of one work package. Use before adding or removing a watcher to verify membership and user IDs; this does not change subscriptions.

Inputs: workPackageId (required).

mark_all_notifications_readA
Idempotent

Mark every visible in-app notification as read for the authenticated user. Use only for an explicit clear-inbox request; this bulk state change is idempotent and does not modify related work packages.

Inputs: no named parameters.

mark_notification_readA
Idempotent

Mark one in-app notification as read for the authenticated user. Use after the notification has been reviewed; this changes inbox state but not the related project resource.

Inputs: id (required).

remove_work_package_watcherA
DestructiveIdempotent

Unsubscribe a user from one work package's watchers. Use only after verifying workPackageId and userId; this changes notification behavior but does not delete the user or work package.

Inputs: userId (required), workPackageId (required).

search_work_packagesA
Read-only

Search visible work packages with focused fields plus optional native filters, sorting, and pagination. Use this for discovery or lists; use get_work_package for the complete resource once an ID is known and count_work_packages for totals only.

Inputs: query, offset, sortBy, dueDate, +7 more.

update_projectA
Idempotent

Patch only the supplied fields on an existing project. Use for renaming, description, visibility, activation, or archival changes; omitted fields are preserved. Requires project administration permission.

Inputs: idOrIdentifier (required), name, active, public, +1 more.

update_work_packageA
Idempotent

Update only the supplied fields on an existing work package and return its browser URL. The tool fetches the current lockVersion first to prevent stale overwrites; null clears supported optional links. It writes immediately and may notify users unless notify is false.

Inputs: id (required), notify, dueDate, subject, +10 more.

upload_work_package_attachmentA

Read one explicit allowlisted local file and upload it to a work package. Use only when the user identified both the file and target task. Paths must be under OPENPROJECT_ALLOWED_UPLOAD_DIRS (default: current working directory). The call rejects files above maxBytes, sends bytes only to the configured OpenProject origin, creates a permanent attachment, and never modifies the local file.

Inputs: filePath (required), workPackageId (required), maxBytes, description.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 41 tools

    Disambiguation5/5

    Each tool targets a distinct entity or operation (e.g., projects, work packages, notifications, attachments). Even similar-sounding tools like list_work_package_priorities and list_work_package_statuses are clearly differentiated by their described purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_projects, create_work_package, delete_work_package_attachment). No mixing of conventions or ambiguous verbs.

    Tool Count4/5

    With 41 tools, the server covers many facets of OpenProject. While the count is high, each tool serves a specific CRUD or discovery need; no obvious bloat. Slightly over but justifiable for an enterprise PM tool.

    Completeness5/5

    The tool set provides full lifecycle coverage for projects, work packages, comments, watchers, attachments, relations, boards, notifications, users, and metadata (versions, priorities, statuses, types). An escape hatch covers any missing endpoints.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers