Welcome to the OpenProjectApiV3Stable* MCP documentation. This guide will help you get started with integrating and using the OpenProjectApiV3Stable* MCP in your client.
- MCP version:
1.0.0
You're looking at the current stable documentation of the OpenProject APIv3. If you're interested in the current development version, please go to github.com/opf.
The documentation for the APIv3 is written according to the OpenAPI 3.1 Specification.
You can either view the static version of this documentation on the website
or the interactive version, rendered with OpenAPI Explorer,
in your OpenProject installation under /api/docs.
In the latter you can try out the various API endpoints directly interacting with our OpenProject data.
Moreover you can access the specification source itself under /api/v3/spec.json and /api/v3/spec.yml
(e.g. here).
The APIv3 is a hypermedia REST API, a shorthand for "Hypermedia As The Engine Of Application State" (HATEOAS). This means that each endpoint of this API will have links to other resources or actions defined in the resulting body.
These related resources and actions for any given resource will be context sensitive. For example, only actions that the authenticated user can take are being rendered. This can be used to dynamically identify actions that the user might take for any given response.
As an example, if you fetch a work package through the Work Package endpoint, the update link will only
be present when the user you authenticated has been granted a permission to update the work package in the assigned project.
HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Read more in the following specification: https://tools.ietf.org/html/draft-kelly-json-hal-08
OpenProject API implementation of HAL+JSON format enriches JSON and introduces a few meta properties:
_type- specifies the type of the resource (e.g.: WorkPackage, Project)_links- contains all related resource and action links available for the resource_embedded- contains all embedded objects
HAL does not guarantee that embedded resources are embedded in their full representation, they might as well be partially represented (e.g. some properties can be left out). However in this API you have the guarantee that whenever a resource is embedded, it is embedded in its full representation.
All API responses contain a single HAL+JSON object, even collections of objects are technically represented by a single HAL+JSON object that itself contains its members. More details on collections can be found in the Collections Section.
The API supports the following authentication schemes: OAuth2, session based authentication, and basic auth.
Depending on the settings of the OpenProject instance many resources can be accessed without being authenticated. In case the instance requires authentication on all requests the client will receive an HTTP 401 status code in response to any request.
Otherwise unauthenticated clients have all the permissions of the anonymous user.
This means you have to login to OpenProject via the Web-Interface to be authenticated in the API. This method is well-suited for clients acting within the browser, like the Angular-Client built into OpenProject.
In this case, you always need to pass the HTTP header X-Requested-With "XMLHttpRequest" for authentication.
Users can authenticate towards the API v3 using basic auth with the user name apikey (NOT your login) and the API key as the password.
Users can find their API key on their account page.
Example:
API_KEY=2519132cdf62dcf5a66fd96394672079f9e9cad1
curl -u apikey:$API_KEY https://community.openproject.org/api/v3/users/42OpenProject allows authentication and authorization with OAuth2 with Authorization code flow, as well as Client credentials operation modes.
To get started, you first need to register an application in the OpenProject OAuth administration section of your installation.
This will save an entry for your application with a client unique identifier (client_id) and an accompanying secret key (client_secret).
You can then use one the following guides to perform the supported OAuth 2.0 flows:
-
Authorization code flow with PKCE, recommended for clients unable to keep the client_secret confidential
-
Client credentials - Requires an application to be bound to an impersonating user for non-public access
There is a possibility to use JSON Web Tokens (JWT) generated by an OIDC provider configured in OpenProject as a bearer token to do authenticated requests against the API. The following requirements must be met:
- OIDC provider must be configured in OpenProject with jwks_uri
- JWT must be signed using RSA algorithm
- JWT iss claim must be equal to OIDC provider issuer
- JWT aud claim must contain the OpenProject client ID used at the OIDC provider
- JWT scope claim must include a valid scope to access the desired API (e.g.
api_v3for APIv3) - JWT must be actual (neither expired or too early to be used)
- JWT must be passed in Authorization header like:
Authorization: Bearer {jwt} - User from sub claim must be logged in OpenProject before otherwise it will be not authenticated
In more general terms, OpenProject should be compliant to RFC 9068 when validating access tokens.
The simplest way to do basic auth would be to use a user's username and password naturally. However, OpenProject already has supported API keys in the past for the API v2, though not through basic auth.
Using username and password directly would have some advantages:
-
It is intuitive for the user who then just has to provide those just as they would when logging into OpenProject.
-
No extra logic for token management necessary.
On the other hand using API keys has some advantages too, which is why we went for that:
-
If compromised while saved on an insecure client the user only has to regenerate the API key instead of changing their password, too.
-
They are naturally long and random which makes them invulnerable to dictionary attacks and harder to crack in general.
Most importantly users may not actually have a password to begin with. Specifically when they have registered through an OpenID Connect provider.
By default, the OpenProject API is not responding with any CORS headers. If you want to allow cross-domain AJAX calls against your OpenProject instance, you need to enable CORS headers being returned.
Please see our API settings documentation on how to selectively enable CORS.
-
GET- Get a single resource or collection of resources -
POST- Create a new resource or perform -
PATCH- Update a resource -
DELETE- Delete a resource
Responses are compressed if requested by the client. Currently gzip and deflate
are supported. The client signals the desired compression by setting the Accept-Encoding header.
If no Accept-Encoding header is send, Accept-Encoding: identity is assumed which will result in the API responding uncompressed.
To get started with the MCP, we recommend installing npm
- Open a terminal, go to the root folder of this project and run the command:
npm run setupThis command will establish a linkage between the MCP server and the SDK, install the required dependencies, and compile the project.
- Copy this object into the MCP configuration file in your client:
{
"mcpServers": {
"liblab": {
"command": "node",
"args": [
"YOUR_FOLDER_ROOT_PATH/dist/index.js"
]
}
}
}Substitute "YOUR_FOLDER_ROOT_PATH" with the absolute path to the directory containing the MCP server.
{
"mcpServers": {
"liblab": {
"command": "node",
"args": [
"YOUR_FOLDER_ROOT_PATH/dist/index.js"
],
"env": {
"BASE_URL": "YOUR_SECRET_VALUE_HERE",
"PASSWORD": "YOUR_SECRET_VALUE_HERE",
"USERNAME": "YOUR_SECRET_VALUE_HERE",
}
}
}
}These are the environment variables for the MCP:
| Name | Description |
|---|---|
| BASE_URL | Optional - Base URL for the API. |
| PASSWORD | Password required for authentication. |
| USERNAME | Username required for authentication. |
Environment variables are a way to configure your application outside the code.
You will have to configure these variables in your client configuration file.
The MCP includes several tools that represent the data structures used in API requests and responses. These tools help in organizing and managing the data efficiently.
Below is a list of all available tools:
| Name | Description |
|---|---|
| Service Root | |
| view_root | Returns the root resource, containing basic information about the server instance and a collection of useful links. |
| Service Actions & Capabilities | |
| list_actions | Returns a collection of actions. The client can choose to filter the actions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain actions, for which the requesting client has sufficient permissions. |
| view_action | Returns an individual action. |
| list_capabilities | Returns a collection of actions assigned to a principal in a context. The client can choose to filter the actions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain actions, for which the requesting client has sufficient permissions |
| view_global_context | Returns the global capability context. This context is necessary to consistently link to a context even if the context is not a project. |
| view_capabilities | View capabilities |
| Service Activities | |
| get_activity | Returns the requested activity resource identified by its unique id. |
| update_activity | Updates an activity's comment and, on success, returns the updated activity. |
| list_activity_attachments | List all attachments of a single activity. |
| create_activity_attachment | Adds an attachment to the specified activity. |
| Service Attachments | |
| create_attachment | Clients can create attachments without a container first and attach them later on. This is useful if the container does not exist at the time the attachment is uploaded. After the upload, the client can then claim such containerless attachments for any resource eligible e.g. WorkPackage on subsequent requests. The upload and the claiming must be done for the same user account. Attachments uploaded by another user cannot be claimed and once claimed for a resource, they cannot be claimed by another. The upload request must be of type multipartform-data with exactly two parts. The first part must be called metadata. Its content type is expected to be applicationjson, the body must be a single JSON object, containing at least the fileName and optionally the attachments description. The second part must be called file, its content type should match the mime type of the file. The body must be the raw content of the file. Note that a filename must be indicated in the Content-Disposition of this part, although it will be ignored. Instead the fileName inside the JSON of the metadata part will be used. |
| view_attachment | View attachment |
| delete_attachment | Permanently deletes the specified attachment. |
| list_attachments_by_meeting | List attachments by meeting |
| add_attachment_to_meeting | Adds an attachment with the meeting as its container. |
| list_attachments_by_post | List attachments by post |
| add_attachment_to_post | Adds an attachment with the post as its container. |
| list_attachments_by_wiki_page | List attachments by wiki page |
| add_attachment_to_wiki_page | Adds an attachment with the wiki page as its container. |
| list_work_package_attachments | List attachments by work package |
| create_work_package_attachment | To add an attachment to a work package, a client needs to issue a request of type multipartform-data with exactly two parts. The first part must be called metadata. Its content type is expected to be applicationjson, the body must be a single JSON object, containing at least the fileName and optionally the attachments description. The second part must be called file, its content type should match the mime type of the file. The body must be the raw content of the file. Note that a filename must be indicated in the Content-Disposition of this part, however it will be ignored. Instead the fileName inside the JSON of the metadata part will be used. |
| Service Budgets | |
| view_budget | view Budget |
| view_budgets_of_a_project | view Budgets of a Project |
| Service Categories | |
| view_category | View Category |
| list_categories_of_a_project | List categories of a project |
| Service Configuration | |
| view_configuration | View configuration |
| Service Custom actions | |
| get_custom_action | Retrieves a custom action by id. |
| execute_custom_action | A POST to this end point executes the custom action on the work package provided in the payload. The altered work package will be returned. In order to avoid executing the custom action unbeknown to a change that has already taken place, the client has to provide the work package's current lockVersion. |
| Service api | |
| get_custom_field_items | Retrieves the hierarchy of custom fields. The hierarchy is a tree structure of hierarchy items. It is represented as a flat list of items, where each item has a reference to its parent and children. The list is ordered in a depth-first manner. The first item is the requested parent. If parent was unset, the root item is returned as first element. Passing the depth query parameter allows to limit the depth of the hierarchy. If the depth is unset, the full hierarchy tree is returned. If the depth is set to 0, only the requested parent is returned. Any other positive integer will return the number of children levels specified by this value. This endpoint only returns, if the custom field is of type hierarchy. |
| get_custom_field_item | Retrieves a single custom field item specified by its unique identifier. |
| get_custom_field_item_branch | Retrieves the branch of a single custom field item specified by its unique identifier. A branch is list of all ancestors, starting with the root item and finishing with the item itself. |
| Service Custom Options | |
| view_custom_option | View Custom Option |
| Service Work Schedule | |
| list_non_working_days | Lists all one-time non working days, such as holidays. It does not lists the non working weekdays, such as each Saturday, Sunday. For listing the weekends, the apiv3days endpoint should be used. All days from current year are returned by default. |
| create_non_working_day | NOT IMPLEMENTED Marks a day as being a non-working day. Note creating a non-working day will not affect the start and finish dates of work packages but will affect their duration. |
| view_non_working_day | Returns the non-working day information for a given date. |
| update_non_working_day | NOT IMPLEMENTED Update the non-working day information for a given date. |
| delete_non_working_day | NOT IMPLEMENTED Removes the non-working day at the given date. Note deleting a non-working day will not affect the start and finish dates of work packages but will affect their duration. |
| list_week_days | Lists week days with work schedule information. |
| update_week_days | NOT IMPLEMENTED Update multiple week days with work schedule information. |
| view_week_day | View a week day and its attributes. |
| update_week_day | NOT IMPLEMENTED Makes a week day a working or non-working day. Note changing a week day working attribute will not affect the start and finish dates of work packages but will affect their duration attribute. |
| list_days | Lists days information for a given date interval. All days from the beginning of current month to the end of following month are returned by default. |
| view_day | View the day information for a given date. |
| Service Documents | |
| list_documents | The documents returned depend on the provided parameters and also on the requesting user's permissions. |
| view_document | View document |
| Service Forms | |
| show_or_validate_form | This is an example of how a form might look like. Note that this endpoint does not exist in the actual implementation. |
| Service Schemas | |
| view_the_schema | This is an example of how a schema might look like. Note that this endpoint does not exist in the actual implementation. |
| Service Collections | |
| view_aggregated_result | view aggregated result |
| Service File links | |
| view_file_link | Gets a single file link resource of a work package. |
| delete_file_link | Removes a file link on a work package. The request contains only the file link identifier as a path parameter. No request body is needed. |
| open_file_link | Creates a uri to open the origin file linked by the given file link. This uri depends on the storage type and is always located on the origin storage itself. |
| download_file_link | Creates a uri to download the origin file linked by the given file link. This uri depends on the storage type and is always located on the origin storage itself. |
| list_project_storages | Gets a collection of all project storages that meet the provided filters and the user has permission to see them. |
| get_project_storage | Gets a project storage resource. This resource contains all data that is applicable on the relation between a storage and a project. |
| open_project_storage | Gets a redirect to the location of the project storage's remote origin. If the project storage has a project folder, it is opened at this location. If not, the storage root is opened. |
| list_storages | Returns a collection of storages. |
| create_storage | Creates a storage resource. When creating a storage, a confidential OAuth 2 provider application is created automatically. The oauth client id and secret of the created OAuth application are returned in the response. IMPORTANT This is the only time, the oauth client secret is visible to the consumer. After that, the secret is hidden. To update the storage with OAuth client credentials, which enable the storage resource to behave as an OAuth 2 client against an external OAuth 2 provider application, another request must be made to create those, see POST apiv3storagesidoauthclientcredentials. |
| get_storage | Gets a storage resource. As a side effect, a live connection to the storages origin is established to retrieve connection state data. |
| update_storage | Updates a storage resource. Only data that is not generated by the server can be updated. This excludes the OAuth 2 application data. |
| delete_storage | Deletes a storage resource. This also deletes all related records, like the created oauth application, client, and any file links created within this storage. |
| get_storage_files | Gets a collection of files from a storage. If no parent context is given, the result is the content of the document root. With parent context given, the result contains the collections of filesdirectories from within the given parent file id. If given parent context is no directory, 400 Bad Request is returned. |
| prepare_storage_file_upload | Executes a request that prepares a link for a direct upload to the storage. The background here is, that the client needs to make a direct request to the storage instance for file uploading, but should not get access to the credentials, which are stored in the backend. The response contains a link object, that enables the client to execute a file upload without the real credentials. |
| create_storage_folder | Creates a new folder under the given parent |
| create_storage_oauth_credentials | Inserts the OAuth 2 credentials into the storage, to allow the storage to act as an OAuth 2 client. Calling this endpoint on a storage that already contains OAuth 2 client credentials will replace them. |
| open_storage | Gets a redirect to the location of the storage's remote origin. The storage's files root should be the target location. |
| Service Grids | |
| list_grids | Lists all grids matching the provided filters and being part of the selected query page. The grids returned will also depend on the permissions of the requesting user. |
| create_grid | Creates a new grid applying the attributes provided in the body. The constraints applied to the grid depend on the page the grid is placed in which is why the create form end point should be used to be guided when wanting to create a grid. |
| grid_create_form | Grid Create Form |
| get_grid | Fetches a single grid identified by its id. |
| update_grid | Updates the given grid by applying the attributes provided in the body. The constraints applied to the grid depend on the page the grid is placed in which is why the create form end point should be used to be guided when wanting to update a grid. |
| grid_update_form | Grid Update Form |
| Service Groups | |
| list_groups | Returns a collection of groups. The client can choose to filter the groups similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain groups, for which the requesting client has sufficient permissions viewmembers, managemembers. |
| create_group | Creates a new group applying the attributes provided in the body. |
| get_group | Fetches a group resource. |
| update_group | Updates the given group by applying the attributes provided in the body. Please note that the members array provided will override the existing set of members similar to a PUT. A client thus has to provide the complete list of members the group is to have after the PATCH even if only one member is to be added. |
| delete_group | Deletes the group. |
| Service Help texts | |
| list_help_texts | List the complete collection of help texts. |
| get_help_text | Fetches the help text from the given id. |
| Service Meetings | |
| view_meeting | Retrieve an individual meeting as identified by the id parameter |
| Service Memberships | |
| list_memberships | Returns a collection of memberships. The client can choose to filter the memberships similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain memberships, for which the requesting client has sufficient permissions viewmembers, managemembers. |
| create_membership | Creates a new membership applying the attributes provided in the body. You can use the form and schema to retrieve the valid attribute values and by that be guided towards successful creation. By providing a notificationMessage within the meta block of the payload, the client can include a customized message to the user of the newly created membership. In case of a group, the message will be sent to every user belonging to the group. By including "sendNotifications" false within the meta block of the payload, no notifications is send out at all. |
| get_memberships_available_projects | Gets a list of projects in which a membership can be created in. The list contains all projects in which the user issuing the request has the manage members permissions. |
| form_create_membership | Requests and validates the creation form for memberships. The request payload, if sent, is validated. The form endpoint itself does not create a membership. |
| get_membership_schema | Retrieves the schema for the membership resource object. |
| get_membership | Retrieves a membership resource identified by the given id. |
| update_membership | Updates the given membership by applying the attributes provided in the body. By providing a notificationMessage within the meta block of the payload, the client can include a customized message to the user of the updated membership. In case of a group, the message will be sent to every user belonging to the group. By including "sendNotifications" false within the meta block of the payload, no notifications is send out at all. |
| delete_membership | Deletes the membership. |
| form_update_membership | Requests and validates the update form for a membership identified by the given id. The request payload, if sent, is validated. The form endpoint itself does not change the membership. |
| Service UserPreferences | |
| show_my_preferences | Show my preferences |
| update_user_preferences | When calling this endpoint the client provides a single object, containing the properties that it wants to change, in the body. |
| Service News | |
| list_news | Lists news. The news returned depend on the provided parameters and also on the requesting user's permissions. |
| create_news | Creates a news entry. Only administrators and users with "Manage news" permission in the given project are eligible. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. |
| view_news | View news |
| update_news | Updates the news's writable attributes. When calling this endpoint the client provides a single object, containing the properties and links to be updated, in the body. |
| delete_news | Permanently deletes the specified news entry. |
| Service Notifications | |
| list_notifications | Returns the collection of available in-app notifications. The notifications returned depend on the provided parameters and also on the requesting user's permissions. Contrary to most collections, this one also links to and embeds schemas for the details properties of the notifications returned. This is an optimization. Clients will receive the information necessary to display the various types of details that a notification can carry. |
| read_notifications | Marks the whole notification collection as read. The collection contains only elements the authenticated user can see, and can be further reduced with filters. |
| unread_notifications | Marks the whole notification collection as unread. The collection contains only elements the authenticated user can see, and can be further reduced with filters. |
| view_notification | Returns the notification identified by the notification id. |
| view_notification_detail | Returns an individual detail of a notification identified by the notification id and the id of the detail. |
| read_notification | Marks the given notification as read. |
| unread_notification | Marks the given notification as unread. |
| Service OAuth 2 | |
| get_oauth_application | Retrieves the OAuth 2 provider application for the given identifier. The secret will not be part of the response, instead a confidential flag is indicating, whether there is a secret or not. |
| get_oauth_client_credentials | Retrieves the OAuth 2 client credentials for the given identifier. The secret will not be part of the response, instead a confidential flag is indicating, whether there is a secret or not. |
| Service Principals | |
| list_placeholder_users | List all placeholder users. This can only be accessed if the requesting user has the global permission manageplaceholderuser or managemembers in any project. |
| create_placeholder_user | Creates a new placeholder user. Only administrators and users with manageplaceholderuser global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. |
| view_placeholder_user | Return the placeholder user resource. |
| update_placeholder_user | Updates the placeholder user's writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. |
| delete_placeholder_user | Set the specified placeholder user to deleted status. |
| list_principals | List all principals. The client can choose to filter the principals similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain principals who are members in projects the client is allowed to see. |
| Service Posts | |
| view_post | Retrieve an individual post as identified by the id parameter |
| Service Priorities | |
| list_all_priorities | List all Priorities |
| view_priority | View Priority |
| Service Projects | |
| list_projects | Returns a collection of projects. The collection can be filtered via query parameters similar to how work packages are filtered. In addition to the provided filter, the result set is always limited to only contain projects the client is allowed to see. |
| create_project | Creates a new project, applying the attributes provided in the body. You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation. |
| project_create_form | Project create form |
| view_project_schema | View project schema |
| view_project | View project |
| update_project | Updates the given project by applying the attributes provided in the body. |
| delete_project | Deletes the project permanently. As this is a lengthy process, the actual deletion is carried out asynchronously. So the project might exist well after the request has returned successfully. To prevent unwanted changes to the project scheduled for deletion, it is archived at once. |
| project_update_form | Project update form |
| create_project_copy | Create project copy |
| project_copy_form | Project copy form |
| view_project_status | View project status |
| list_available_parent_project_candidates | Lists projects which can become parent to another project. Only sound candidates are returned. For instance a project cannot become parent of itself or its children. To specify the project for which a parent is queried for, the of parameter can be provided. If no of parameter is provided, a new project is assumed. Then, the check for the hierarchy is omitted as a new project cannot be part of a hierarchy yet. Candidates can be filtered. Most commonly one will want to filter by name or identifier. You can do this through the filters parameter which works just like the work package index. For instance to find all parent candidates with "rollout" in their name filters"nameandidentifier""operator""","values""rollout" |
| list_projects_with_version | This endpoint lists the projects where the given version is available. The projects returned depend on the sharing settings of the given version, but are also limited to the projects that the current user is allowed to see. |
| Service Queries | |
| view_default_query_for_project | Same as viewing an existing, persisted Queryhttpswww.openproject.orgdocsapiendpointsquerieslist-queries in its response, this resource returns an unpersisted query and by that allows to get the default query configuration. The client may also provide additional parameters which will modify the default query. The query will already be scoped for the project. |
| view_schema_for_project_queries | Retrieve the schema for project queries. |
| list_queries | Returns a collection of queries. The collection can be filtered via query parameters similar to how work packages are filtered. Please note however, that the filters are applied to the queries and not to the work packages the queries in turn might return. |
| create_query | When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a Query can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation. |
| available_projects_for_query | Gets a list of projects that are available as projects a query can be assigned to. |
| view_default_query | Same as viewing an existing, persisted Queryhttpswww.openproject.orgdocsapiendpointsquerieslist-queries in its response, this resource returns an unpersisted query and by that allows to get the default query configuration. The client may also provide additional parameters which will modify the default query. |
| query_create_form | Query Create Form |
| view_schema_for_global_queries | Retrieve the schema for global queries, those, that are not assigned to a project. |
| view_query | Retrieve an individual query as identified by the id parameter. Then end point accepts a number of parameters that can be used to override the resources' persisted parameters. |
| edit_query | When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. Note that it is only allowed to provide properties or links supporting the write operation. |
| delete_query | Delete the query identified by the id parameter |
| query_update_form | Query Update Form |
| star_query | Star query |
| unstar_query | Unstar query |
| Service Query Filter Instance Schema | |
| list_query_filter_instance_schemas_for_project | Returns the list of QueryFilterInstanceSchemas defined for a query of the specified project. |
| list_query_filter_instance_schemas | Returns the list of QueryFilterInstanceSchemas defined for a global query. That is a query not assigned to a project. |
| view_query_filter_instance_schema | Retrieve an individual QueryFilterInstanceSchema as identified by the id parameter. |
| Service Work Packages | |
| get_project_work_package_collection | Returns the collection of work packages that are related to the given project. |
| create_project_work_package | When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation. |
| form_create_work_package_in_project | This endpoint allows you to validation a new work package creation body in a specific project. It works similarly to the apiv3workpackagesform endpoint, but already specifies the work package's project in the path, so that it does not have to be defined in the request body. |
| project_available_assignees | Gets a list of users that can be assigned to work packages in the given project. |
| list_work_packages | Returns a collection of work packages. |
| create_work_package | When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation. A project link must be set when creating work packages through this route. When setting start date, finish date, and duration together, their correctness will be checked and a 422 error will be returned if one value does not match with the two others. You can make the server compute a value set only two values in the request and the third one will be computed and returned in the response. For instance, when sending "startDate" "2022-08-23", duration "P2D" , the response will include "dueDate" "2022-08-24" . |
| form_create_work_package | When calling this endpoint, the client provides a single object containing the properties and links to be created, in the body. The input is validated and a schema response is returned. If the validation errors of the response is empty, the same payload can be used to create a work package. Only the properties of the work package write model are allowed to set on a work package on creation. When setting start date, finish date, and duration together, their correctness will be checked and a validation error will be returned if one value does not match with the two others. You can make the server compute a value set only two values in the request and the third one will be computed and returned in the response. For instance, when sending "startDate" "2022-08-23", duration "P2D" , the response will include "dueDate" "2022-08-24" . |
| list_work_package_schemas | List all work package schemas that match the given filters. This endpoint does not return a successful response, if no filter is given. |
| view_work_package_schema | View Work Package Schema |
| view_work_package | Returns the specified work package. |
| update_work_package | When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. Note that it is only allowed to provide properties or links supporting the write operation. Additionally to the fields the client wants to change, it is mandatory to provide the value of lockVersion which was received by the GET request this change originates from. The value of lockVersion is used to implement optimistic lockinghttpsen.wikipedia.orgwikiOptimisticconcurrencycontrol. |
| delete_work_package | Deletes the work package, as well as - all associated time entries - its hierarchy of child work packages |
| list_work_package_activities | List work package activities |
| comment_work_package | Creates an activity for the selected work package and, on success, returns the updated activity. |
| work_package_available_assignees | Gets a list of users that can be assigned to the given work package. |
| available_projects_for_work_package | Gets a list of projects that are available as projects to which the work package can be moved. |
| list_available_relation_candidates | Available relation candidates |
| available_watchers | Gets a list of users that are able to be watchers of the specified work package. |
| list_work_package_file_links | Gets all file links of a work package. As a side effect, for every file link a request is sent to the storage's origin to fetch live data and patch the file link's data before returning, as well as retrieving permissions of the user on this origin file. |
| create_work_package_file_link | Creates file links on a work package. The request is interpreted as a bulk insert, where every element of the collection is validated separately. Each element contains the origin meta data and a link to the storage, the file link is about to point to. The storage link can be provided as a resource link with id or as the host url. The file's id and name are considered mandatory information. The rest of the origin meta data SHOULD be provided by the client. The mimeType SHOULD be a standard mime type. An empty mime type will be handled as unknown. To link a folder, the custom mime type applicationx-op-directory MUST be used. Up to 20 file links can be submitted at once. If any element data is invalid, no file links will be created. If a file link with matching origin id, work package, and storage already exists, then it will not create an additional file link or update the meta data. Instead the information from the existing file link will be returned. |
| form_edit_work_package | When calling this endpoint, the client provides a single object containing the properties and links to be edited, in the body. The input is validated and a schema response is returned. If the validation errors of the response is empty, the same payload can be used to edit the work package. Only the properties of the work package write model are allowed to set on a work package on editing. When setting start date, finish date, and duration together, their correctness will be checked and a validation error will be returned if one value does not match with the two others. You can make the server compute a value set only two values in the request and the third one will be computed and returned in the response. For instance, when sending "startDate" "2022-08-23", duration "P2D" , the response will include "dueDate" "2022-08-24" . |
| revisions | Gets a list of revisions that are linked to this work package, e.g., because it is referenced in the commit message of the revision. Only linked revisions from repositories are shown if the user has the view changesets permission in the defining project. |
| reminders | Gets a list of your upcoming reminders for this work package. |
| list_watchers | List watchers |
| add_watcher | Adds a watcher to the specified work package. The request is expected to contain a single JSON object, that contains a link object under the user key. The response will be user added as watcher. In case the user was already watching the work package an HTTP 200 is returned, an HTTP 201 if the user was added as a new watcher. |
| remove_watcher | Removes the specified user from the list of watchers for the given work package. If the request succeeds, the specified user is not watching the work package anymore. Note This might also be the case, if the specified user did not watch the work package prior to the request. |
| Service Types | |
| list_types_available_in_a_project | This endpoint lists the types that are available in a given project. |
| list_all_types | List all Types |
| view_type | View Type |
| Service Versions | |
| list_versions_available_in_a_project | This endpoint lists the versions that are available in a given project. Note that due to sharing this might be more than the versions defined by that project. |
| list_versions | Returns a collection of versions. The client can choose to filter the versions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain versions, for which the requesting client has sufficient permissions viewworkpackages. |
| create_version | Creates a new version applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a version's attributes and are accepted by the endpoint. You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation. |
| available_projects_for_versions | Gets a list of projects in which a version can be created in. The list contains all projects in which the user issuing the request has the manage versions permissions. |
| version_create_form | Version create form |
| view_version_schema | View version schema |
| view_version | View version |
| update_version | Updates the given version by applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a version's attributes and are accepted by the endpoint. |
| delete_version | Deletes the version. Work packages associated to the version will no longer be assigned to it. |
| version_update_form | Version update form |
| Service Query Columns | |
| view_query_column | Retrieve an individual QueryColumn as identified by the id parameter. |
| Service Query Filters | |
| view_query_filter | Retrieve an individual QueryFilter as identified by the id parameter. |
| Service Query Operators | |
| view_query_operator | Retrieve an individual QueryOperator as identified by the id parameter. |
| Service Query Sort Bys | |
| view_query_sort_by | Retrieve an individual QuerySortBy as identified by the id parameter. |
| Service Relations | |
| list_relations | Lists all relations according to the given optional, logically conjunctive filters and ordered by ID. The response only includes relations between work packages which the user is allowed to see. |
| get_relation | Get a single relation specified by its unique identifier. |
| update_relation | When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. It is only allowed to provide properties or links supporting the write operation. Note that changing the type of a relation invariably also changes the respective reverseType as well as the "name" of it. The returned Relation object will reflect that change. For instance if you change a Relation's type to "follows" then the reverseType will be changed to precedes. It is not allowed to change a relation's involved work packages. |
| delete_relation | Deletes the relation. |
| create_relation | Create a work package relation on the given work package. A successful creation will result in a relation between two work packages, thus appearing on both involved work package resources. |
| Service Previewing | |
| preview_markdown_document | Preview Markdown document |
| preview_plain_document | Preview plain document |
| Service Revisions | |
| view_revision | View revision |
| Service Roles | |
| list_roles | List all defined roles. This includes built in roles like 'Anonymous' and 'Non member'. |
| view_role | Fetch an individual role. |
| Service Statuses | |
| list_statuses | Returns a collection of all work package statuses. |
| get_status | Returns a work package status by its unique identifier. |
| Service Time entries | |
| list_time_entries | Lists time entries. The time entries returned depend on the filters provided and also on the permission of the requesting user. |
| create_time_entry | Creates a new time entry applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries' attributes and are accepted by the endpoint. |
| time_entry_update_form | Time entry update form |
| available_projects_for_time_entries | Gets a list of projects in which a time entry can be created in or be assigned to on update. The list contains all projects in which the user issuing the request has the necessary permissions. |
| time_entry_create_form | Time entry create form |
| view_time_entry_schema | View time entry schema |
| get_time_entry | Retrieves a single time entry identified by the given id. |
| update_time_entry | Updates the given time entry by applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries' attributes and are accepted by the endpoint. |
| delete_time_entry | Permanently deletes the specified time entry. |
| Service Time entry activities | |
| get_time_entries_activity | Fetches the time entry activity resource by the given id. |
| Service Users | |
| list_users | Lists users. Only administrators or users with any of the following can access this resource - managemembers - manageuser - shareworkpackages |
| create_user | Creates a new user. Only administrators and users with manageuser global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. Valid values for status 1 "active" - In this case a password has to be provided in addition to the other attributes. 2 "invited" - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user. |
| view_user_schema | The schema response use two exemplary custom fields that extend the schema response. Depending on your instance and custom field configuration, the response will look somewhat different. |
| view_user | View user |
| update_user | Updates the user's writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. |
| delete_user | Permanently deletes the specified user account. |
| user_update_form | User update form |
| lock_user | Lock user |
| unlock_user | Unlock user |
| Service Values::Property | |
| view_values_schema | The schema of a Values resource. |
| Service Views | |
| list_views | Returns a collection of Views. The collection can be filtered via query parameters similar to how work packages are filtered. |
| view_view | View view |
| create_views | When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a View can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation. There are different subtypes of Views e.g. ViewsWorkPackagesTable with each having its own endpoint for creating that subtype e.g. apiv3viewsworkpackagestable for ViewsWorkPackagesTable apiv3viewsteamplanner for ViewsTeamPlanner apiv3viewsworkpackagescalendar for ViewsWorkPackagesCalendar Not yet implemented To get the list of available subtypes and by that the endpoints for creating a subtype, use the apiv3viewsschemas endpoint. |
| Service Wiki Pages | |
| view_wiki_page | Retrieve an individual wiki page as identified by the id parameter |
| Service General | |
| restart_sdk | Restart the SDK with the variables passed as parameters |
# Clone the repository
git clone https://github.com/boma086/openproject-api-v3-stable-mcp.git
cd openproject-api-v3-stable-mcp
# Install and build
npm run setup{
"mcpServers": {
"openproject": {
"command": "node",
"args": ["/path/to/openproject-api-v3-stable-mcp/dist/index.js"],
"env": {
"BASE_URL": "https://your-openproject.com",
"USERNAME": "your-username",
"PASSWORD": "your-password"
}
}
}
}{
"mcpServers": {
"openproject": {
"command": "npx",
"args": ["openproject-api-v3-stable-mcp"],
"env": {
"BASE_URL": "https://your-openproject.com",
"USERNAME": "your-username",
"PASSWORD": "your-password"
}
}
}
}