OpenProject MCP Server
Provides tools to manage OpenProject from Codex, including searching, creating, updating, and commenting on work packages, as well as listing projects, using the OpenProject API v3.
OpenProject for Codex
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-pluginMCP 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.envSet your OpenProject URL and API token in that file:
OPENPROJECT_URL=https://tasks.example.com
OPENPROJECT_API_TOKEN=your-api-tokenInstall the MCP integration:
./scripts/install.shWindows
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.ps1The installer passes paths as separate arguments, so repository and profile paths containing spaces work on every supported desktop OS.
Optional configuration
Variable | Default | Purpose |
|
| Default collection page size, from 1 to 100 |
|
| Request timeout, from 1 to 300 seconds |
|
| Use |
| 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.envTools
The 41 tools form one consistent OpenProject API surface:
Area | Read tools | Write tools |
Projects |
|
|
Work packages |
|
|
Attachments |
|
|
Relations |
|
|
Users |
| — |
Watchers |
|
|
Notifications |
|
|
Boards |
| — |
Reference data |
| — |
Advanced |
| — |
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
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 checkGenerate a local coverage report with:
bun run test:coverageThe 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 testsPlanned work is tracked in the project roadmap. Contributions and well-scoped feature proposals are welcome.
Uninstall
macOS and Linux:
./scripts/uninstall.shWindows PowerShell:
.\scripts\uninstall.ps1Project 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
Available Tools
41 toolsadd_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_watcherAIdempotent
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_projectsARead-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_packagesARead-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_projectADestructiveIdempotent
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_packageADestructiveIdempotent
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_attachmentADestructiveIdempotent
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_relationADestructiveIdempotent
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_boardARead-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_userARead-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_notificationARead-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_apiARead-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_projectARead-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_userARead-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_packageARead-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_attachmentARead-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_relationARead-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_assigneesARead-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_lanesARead-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_boardsARead-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_notificationsARead-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_projectsARead-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_versionsARead-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_usersARead-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_activitiesARead-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_attachmentsARead-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_prioritiesARead-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_relationsARead-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_statusesARead-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_typesARead-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_watchersARead-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_readAIdempotent
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_readAIdempotent
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_watcherADestructiveIdempotent
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_packagesARead-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_projectAIdempotent
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_packageAIdempotent
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
Scored across 41 tools
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.
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.
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.
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
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with self-hosted OpenProject instances through the MCP protocol, supporting CRUD operations for projects and tasks (work packages) with pagination and filtering capabilities.8MIT
- FlicenseAqualityDmaintenanceExposes the OpenProject REST API as MCP tools for project management, including creating and managing projects, work packages, relations, attachments, users, notifications, watchers, boards, and reference data.37-
- AlicenseNot gradedqualityCmaintenanceMCP server enabling AI agents to interact with OpenProject API v3 for project management, including creating and managing work packages, projects, comments, time entries, boards, and user dashboards.MIT
- AlicenseAqualityDmaintenanceMCP server for OpenProject that enables AI agents to search and view work packages, add comments, upload attachments, log time, list projects, and search users via the REST API v3.10MIT