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:

git clone <your-repo-url>
cd openproject-mcp

2. Install dependencies:

uv sync

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

cp .env.example .env

4. Configure your OpenProject credentials in .env:

OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_KEY=your_api_key_here

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:

cp .env.example .env
# Edit .env with your OpenProject URL and API key

2. Build and run with Docker Compose:

docker-compose up -d

3. View logs:

docker-compose logs -f

4. Stop the server:

docker-compose down

Using Docker directly

1. Build the Docker image:

docker build -t openproject-mcp .

2. Run the container:

docker run -it --rm \
  -e OPENPROJECT_URL=https://your-instance.openproject.com \
  -e OPENPROJECT_API_KEY=your_api_key_here \
  openproject-mcp

Using with Claude Desktop (Docker)

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

{
  "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"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "openproject": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/openproject-mcp",
        "run",
        "openproject-mcp"
      ],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your_api_key_here"
      }
    }
  }
}

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:

Create a new task in project "demo-project" with subject "Fix login bug" and description "Users cannot log in with special characters in password"

Get work package details:

Get details for work package #123

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:

Update work package #123: change status to "In Progress" and assign to user 5

List work packages:

List all work packages in project "demo-project"

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:

Set work package #456 as the parent of work package #123

Comments

Add a comment:

Add a comment to work package #123: "I've started working on this issue"

Get activities:

Show me all activities and comments for work package #123

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

Projects

Get project details:

Get details for project "demo-project"

List projects:

List all active projects

Update project:

Update project "demo-project": change description to "Demo project for testing"

Relations

Create a relation:

Create a "blocks" relation from work package #123 to work package #456

List relations:

Show all relations for work package #123

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

uv run pytest

Code Formatting

uv run black src/

Type Checking

uv run mypy src/

Linting

uv run ruff check src/

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

openproject-mcp/
├── src/openproject_mcp/
│   ├── server.py              # Main MCP server
│   ├── client.py              # OpenProject API client
│   ├── config.py              # Configuration management
│   ├── tools/
│   │   ├── work_packages.py   # Work package tools
│   │   ├── comments.py        # Comment tools
│   │   ├── projects.py        # Project tools
│   │   └── relations.py       # Relation tools
│   └── utils/
│       ├── errors.py          # Custom exceptions
│       └── hal.py             # HAL+JSON helpers
├── tests/                     # Test files
├── pyproject.toml             # Dependencies
├── .env.example               # Example environment variables
└── README.md                  # This file

Authentication

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

Authorization: Basic base64(apikey:<your_api_key>)

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.