OpenProject MCP Server

A Model Context Protocol (MCP) server for OpenProject API v3 integration. This server provides comprehensive tools for managing work packages, comments, projects, and relations in OpenProject through Claude Desktop and other MCP clients.

Features

• Work Package Management (10 tools)

  • Create, read, update, delete work packages

  • Manage assignees and watchers

  • Set parent-child relationships

  • Get work package schema

• Comment & Activity Management (4 tools)

  • Get work package activities

  • Create and update comments

  • View activity details

• Project Management (3 tools)

  • Get project details

  • List projects with filtering

  • Update project properties

• Relation Management (4 tools)

  • List work package relations

  • Create relations (relates, blocks, precedes, etc.)

  • Delete relations

Installation

Prerequisites

• Python 3.11 or higher

• uv package manager

• OpenProject account with API access

Setup

1. Clone the repository:

2. Install dependencies:

3. Create a .env file (copy from .env.example):

4. Configure your OpenProject credentials in .env:

Getting Your API Key

1. Log in to your OpenProject instance

2. Go to My Account (top-right menu)

3. Select Access tokens from the left sidebar

4. Click + API to generate a new API key

5. Copy the key and paste it into your .env file

Docker Installation (Alternative)

You can also run the server using Docker:

Using Docker Compose (Recommended)

1. Create a .env file with your credentials:

2. Build and run with Docker Compose:

3. View logs:

4. Stop the server:

Using Docker directly

1. Build the Docker image:

2. Run the container:

Using with Claude Desktop (Docker)

To use the Docker container with Claude Desktop, update your configuration:

Usage with Claude Desktop

Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Replace /absolute/path/to/openproject-mcp with the actual path to this project directory.

Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the server.

Example Usage

Work Packages

Create a work package:

Get work package details:

Note: Work package details are returned as formatted markdown with all key information including status, type, priority, project, hierarchy, costs, and description.

Update a work package:

List work packages:

Note: Work packages are displayed as a formatted list showing ID, subject, type, status, priority, project, assignee, due date, and parent (if any).

Set parent work package:

Comments

Add a comment:

Get activities:

Note: Activities are returned as formatted markdown with user, timestamp, comments, and change details for easy reading.

Projects

Get project details:

List projects:

Update project:

Relations

Create a relation:

List relations:

Available Tools

Work Package Tools

1. create_work_package - Create a new work package

2. get_work_package - Get work package details (formatted as markdown)

3. update_work_package - Update work package fields

4. list_work_packages - List work packages with filtering (formatted as markdown)

5. delete_work_package - Delete a work package

6. get_available_assignees - Get assignable users for a project

7. add_watcher - Add a watcher to a work package

8. remove_watcher - Remove a watcher

9. get_work_package_schema - Get schema for work package creation

10. set_parent_work_package - Set or remove the parent of a work package

Comment Tools

1. get_work_package_activities - Get all activities/comments (formatted as markdown)

2. create_comment - Add a comment to a work package

3. get_activity - Get specific activity details

4. update_comment - Update an existing comment

Project Tools

1. get_project - Get project details

2. list_projects - List all accessible projects

3. update_project - Update project properties

Relation Tools

1. list_work_package_relations - Get all relations for a work package

2. create_relation - Create a relation between work packages

3. get_relation - Get specific relation details

4. delete_relation - Delete a relation

Relation Types

When creating relations, you can use the following types:

• relates - General relation

• duplicates - Source duplicates target

• duplicated - Source is duplicated by target

• blocks - Source blocks target

• blocked - Source is blocked by target

• precedes - Source precedes target (supports lag in days)

• follows - Source follows target (supports lag in days)

• includes - Source includes target (parent-child)

• partof - Source is part of target (child-parent)

• requires - Source requires target

• required - Source is required by target

Development

Running Tests

Code Formatting

Type Checking

Linting

Architecture

The server is built with:

• FastMCP - Official MCP Python SDK for tool definition

• httpx - Async HTTP client for OpenProject API calls

• Pydantic - Configuration and data validation

• python-dotenv - Environment variable management

Project Structure

Authentication

The server uses API key authentication with OpenProject. The API key is encoded as Basic Auth:

All requests are made to the OpenProject API v3 endpoint (/api/v3/).

Error Handling

The server includes comprehensive error handling for common scenarios:

• 401 Unauthorized - Invalid API key

• 403 Forbidden - Insufficient permissions

• 404 Not Found - Resource doesn't exist

• 409 Conflict - Lock version mismatch (fetch latest and retry)

• 422 Unprocessable Entity - Validation errors

• 429 Too Many Requests - Rate limit exceeded

Lock Versions

OpenProject uses optimistic locking to prevent concurrent modifications. When updating resources (work packages, projects, comments), you must provide the current lockVersion:

1. Fetch the resource to get the current lockVersion

2. Make your changes

3. Send the update with the lockVersion

4. If you get a 409 Conflict, fetch the resource again and retry

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

[Your License Here]

Support

For issues and questions:

• OpenProject API Documentation: https://www.openproject.org/docs/api/

• MCP Documentation: https://modelcontextprotocol.io/

Acknowledgments

Built with the Model Context Protocol and OpenProject API v3.