OpenProject

You can run and use the OpenProject MCP Server to manage work packages, comments, projects, and relations through MCP clients like Claude Desktop. This server exposes a structured set of tools that let you perform create/read/update/delete operations and keep data in sync with your OpenProject instance via API keys and secure access.

How to use

Connect to your OpenProject MCP Server from an MCP client using the provided STDIO configuration. Run the server container locally or in your environment and then start issuing MCP tool commands to manage work packages, comments, projects, and relations. The server authenticates with your OpenProject instance using an API key, so keep that key secure.

Key capabilities you can leverage include creating, reading, updating, and deleting work packages; managing assignees and watchers; handling parent-child relationships; retrieving work package schemas; managing comments and activities; querying project details and lists; and creating, listing, and deleting relations between work packages. All actions respect OpenProject API v3 semantics and use optimistic locking via lockVersion to prevent concurrent update conflicts.

To use the Docker-based runtime, you can run the container with your OpenProject URL and API key. The example below shows how to start the MCP server using Docker, passing your credentials as environment variables.

How to install

Prerequisites you need before installation are: Python 3.11 or higher and the uv package manager to install and run MCPs. You also need an OpenProject account with API access.

Step by step setup you can follow exactly:

# Optional: clone the project
git clone <your-repo-url>
cd openproject-mcp

# Install dependencies via the UV manager
uv sync

# Copy environment file and fill credentials
cp .env.example .env
# Edit .env to set your OpenProject URL and API key

Additional configuration and run notes

Environment variables you must provide include OPENPROJECT_URL and OPENPROJECT_API_KEY. These values are used to authenticate requests to the OpenProject API v3.

If you prefer to run the server in a Docker container, set up a .env file with your credentials and use Docker to start the container. The Docker approach is flexible for local development and testing.

Starting via Claude Desktop with Docker is supported. You will provide a JSON configuration that runs Docker to execute the MCP server image and pass credentials through environment variables.

Claude Desktop configuration example

{
  "mcpServers": {
    "openproject": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENPROJECT_URL=https://your-instance.openproject.com",
        "-e",
        "OPENPROJECT_API_KEY=your_api_key_here",
        "openproject-mcp"
      ]
    }
  }
}

Example usage patterns

Create a new work package in a project, then fetch its details, and finally update its status or assignee. You can also add comments, list activities, and manage relations between work packages.

Examples of typical workflows include creating a work package, listing work packages with filters, getting project details, and establishing relations such as blocks or relates between work packages.

Security and error handling

The server uses an OpenProject API key for authentication. Treat the API key as a secret and restrict access to systems that host the MCP server. Error handling includes clearly communicated HTTP-like errors such as 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, and 429 Too Many Requests. If you encounter a 409 Conflict, fetch the latest resource and retry with the updated lockVersion.

Troubleshooting

If you cannot reach OpenProject, verify that OPENPROJECT_URL is correct and that OPENPROJECT_API_KEY has the necessary permissions. Ensure the container or process running the MCP server has outbound network access to the OpenProject instance.

Notes

All operations respect the OpenProject API v3 semantics. For concurrent updates, you must provide the current lockVersion to avoid conflicts. When listing or querying resources, results are paginated and can be filtered based on project, status, type, and other OpenProject-supported criteria.

Tools and capabilities (summary)

The server exposes a comprehensive set of tools for Work Packages, Comments, Projects, and Relations. Each tool corresponds to a specific action such as creating, reading, updating, or deleting resources, managing relationships, and retrieving schemas or activities.

Available tools

create_work_package

Create a new work package in a project with details like subject, description, type, and priority.

get_work_package

Retrieve details of a specific work package, including status, type, priority, assignee, and related metadata.

update_work_package

Update fields of an existing work package, including status, assignee, and hierarchy, using the current lockVersion to prevent conflicts.

list_work_packages

List work packages with filtering options such as project, status, type, and assignee; results are presented in a structured, readable format.

delete_work_package

Delete a work package by its identifier.

get_available_assignees

Fetch users who can be assigned to a work package within a project.

add_watcher

Add a watcher to a work package to receive updates.

remove_watcher

Remove a watcher from a work package.

get_work_package_schema

Retrieve the schema for creating or updating work packages.

set_parent_work_package

Set or remove the parent of a work package to manage hierarchy.

get_work_package_activities

Get all activities and comments for a work package.

create_comment

Add a new comment to a work package.

get_activity

Get details of a specific activity or comment.

update_comment

Update an existing comment on a work package.

get_project

Fetch details for a specific project.

list_projects

List all accessible projects with optional filters.

update_project

Update project properties such as description or other metadata.

list_work_package_relations

List all relations for a given work package.

create_relation

Create a relation between two work packages (relates, blocks, precedes, etc.).

get_relation

Retrieve details of a specific relation.

delete_relation

Delete a relation between work packages.