openproject-mcp

# OpenProject MCP Server

<!-- mcp-name: io.github.kar-thik/openproject-mcp-server -->

[![PyPI](https://img.shields.io/pypi/v/openproject-mcp-server)](https://pypi.org/project/openproject-mcp-server/)
[![CI](https://github.com/kar-thik/openproject-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kar-thik/openproject-mcp/actions/workflows/ci.yml)
[![openproject-mcp MCP server](https://glama.ai/mcp/servers/kar-thik/openproject-mcp/badges/score.svg)](https://glama.ai/mcp/servers/kar-thik/openproject-mcp)

An MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) server for the
[OpenProject](https://www.openproject.org/) API v3. It gives Claude and any other MCP client
88 tools covering work packages, comments and relations, attachments, git/PR activity, projects,
saved queries, notifications, time tracking, versions, people and memberships, meetings, news,
documents, budgets and reporting — plus 4 report/workflow prompts and 3 resource templates.
Built on FastMCP 3.x and httpx (HTTP/2).

This project is aimed at the OpenProject **Community edition**. OpenProject's Enterprise
edition now ships with its own built-in MCP integration; this server brings the same
capability to self-hosted Community instances. It runs fine against any edition — it only
needs the public API v3.

Design principles, all enforced in code:

- **Structured everything.** Every tool returns a typed model, so clients get an
  `outputSchema` and machine-readable `structuredContent`, not prose. Errors come back as a
  JSON envelope with a stable `type`, the upstream `http_status`, a `message` and a `hint`
  describing how to correct the call.
- **Honest degradation.** OpenProject instances differ by version, installed modules and
  permissions. Tools report what they could not see as in-band notes — a missing module yields
  an empty page with an explanation, never a fake success or a bare traceback.
- **Safe by default.** A read-only mode, admin-gated membership writes, per-group tool
  disabling, a `confirm=true` guard on every destructive tool, TLS always verified, and
  credentials that never appear in logs.
- **Version-adaptive.** Targets OpenProject 14 LTS through 17.x; API differences are detected
  by a lazy, cached feature probe instead of assumptions (see
  [Supported OpenProject versions](#supported-openproject-versions)).

## What it looks like

Two exchanges against a fictional "Website Relaunch" project — every id, name and date below
is invented. You describe the outcome; the model picks the tools, and what comes back to it
is a typed object rather than prose to re-parse.

```text
You         What is still open in Website Relaunch and due by Friday? The checkout
            bug is urgent — raise it and leave a note for whoever owns it.

  →  list_work_packages(project="website-relaunch", status_scope="open",
                        due_before="2026-03-13", sort_by=[["due_date", "asc"]])

     { "items": [
         { "id": 4821, "subject": "Checkout fails on expired coupon codes",
           "type": {"id": 7, "name": "Bug"}, "status": {"id": 7, "name": "In progress"},
           "assignee": {"id": 118, "name": "Dana Okafor"}, "due_date": "2026-03-11" },
         { "id": 4830, "subject": "Move press-kit assets to the new CDN",
           "type": {"id": 1, "name": "Task"}, "status": {"id": 1, "name": "New"},
           "assignee": null, "due_date": "2026-03-13" }],
       "pagination": {"total": 2, "page": 1, "page_size": 20, "has_more": false} }

  →  update_work_package(id=4821, priority="High")
  →  add_work_package_comment(id=4821, comment="Raised to High — it blocks the
                              launch checklist. Dana, can you take a look today?")

Assistant   Two open items are due by Friday. #4821 is High now and the note is on
            its thread; #4830 is due Friday and still has nobody on it.
```

The rows above are abridged: each one also carries `priority`, `project`, `start_date`,
`percentage_done` and `updated_at`, and the envelope keeps `groups`, `sums` and `notes` slots
for the calls that fill them.

The prompt templates cut out the tool round trips: the server reads OpenProject itself and
hands back a finished document rather than instructions to go and fetch one. It arrives
prefaced with a note that the numbers are already computed and must not be recomputed or
embellished.

```text
You         /weekly_report project=website-relaunch

            # WEEKLY REPORT - AGILE SCRUM

            _Generated from live OpenProject data_
            ...
            ## B. EXECUTIVE SUMMARY

            **Progress against the sprint goal:** Not assessed — sprint goal and completion dates are not available

            **Currently closed work updated in the window:**
            1. #4802 - Ship the new pricing page
            2. #4795 - Halve the hero image payload
            ...
            ### Data notes

            - open/closed bucketing uses each status's isClosed flag from
              GET /statuses, not status names; a status this instance renamed
              or translated is still bucketed correctly
```

That last block is the house style: a report says which of its numbers are partial, and a
tool that could not read something returns the gap as a note instead of guessing. The whole
surface is in [Tools](#tools) and [Prompts and resources](#prompts-and-resources).

## Requirements

- Python >= 3.12
- An OpenProject instance, version 14 LTS through 17.x (any edition; aimed at Community —
  Enterprise ships its own MCP integration)
- An OpenProject API key: in OpenProject, go to **My account → Access tokens** and generate an
  API token

## Installation

The distribution name is `openproject-mcp-server`. It installs two identical console scripts,
`openproject-mcp-server` and `openproject-mcp`; the long form is canonical (an unrelated PyPI
package also installs a bin named `openproject-mcp`).

Run one-shot with [uv](https://docs.astral.sh/uv/), no install step:

```sh
uvx openproject-mcp-server
```

Or install persistently:

```sh
uv tool install openproject-mcp-server
# or
pip install openproject-mcp-server
```

The minimal configuration is two environment variables:

```sh
export OPENPROJECT_URL=https://openproject.example.com
export OPENPROJECT_API_KEY=your-api-key
```

Validate the configuration without starting the server:

```sh
openproject-mcp-server --check
```

`--check` verifies the configuration and exits; it does not contact your instance. Once
connected through a client, call the `get_instance_info` tool for a live end-to-end check.
When configuration is missing or invalid, the server prints the specific problems to stderr
and exits with code 2 — never a traceback.

### Claude Code

```sh
claude mcp add openproject \
  --env OPENPROJECT_URL=https://openproject.example.com \
  --env OPENPROJECT_API_KEY=your-api-key \
  -- uvx openproject-mcp-server
```

### Claude Desktop and other MCP clients

Add to `claude_desktop_config.json` (or your client's equivalent `mcpServers` config):

```json
{
  "mcpServers": {
    "openproject": {
      "command": "uvx",
      "args": ["openproject-mcp-server"],
      "env": {
        "OPENPROJECT_URL": "https://openproject.example.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}
```

### From source

```sh
git clone https://github.com/kar-thik/openproject-mcp
cd openproject-mcp
uv sync
uv run openproject-mcp-server
```

## Updating or rotating your API token

When a token is regenerated, revoked or invalidated (OpenProject major upgrades can do this —
the symptom is every tool suddenly failing with `authentication_failed` / HTTP 401), generate
a fresh one in OpenProject under **My account → Access tokens** and update it wherever your
key lives:

- **Shell environment (easiest to rotate).** The server reads `OPENPROJECT_API_KEY` straight
  from the OS environment, so you can export it globally — e.g. in `~/.zshenv` — and register
  the server with no `--env` flags at all:

  ```sh
  claude mcp add openproject -- uvx openproject-mcp-server
  ```

  Rotation is then: edit the export, open a fresh terminal, reconnect. The client config
  never contains a secret. (This does not work for GUI apps like Claude Desktop, which don't
  read your shell profile.)
- **Claude Code with `--env`.** The registration stores the key, so replace it:

  ```sh
  claude mcp remove openproject
  claude mcp add openproject \
    --env OPENPROJECT_URL=https://openproject.example.com \
    --env OPENPROJECT_API_KEY=new-key \
    -- uvx openproject-mcp-server
  ```

  Then reconnect via `/mcp` (a running session keeps the old environment until it does).
- **Claude Desktop and other JSON-configured clients.** Edit the `OPENPROJECT_API_KEY` value
  in the client config and restart the client.
- **`.env` file.** Edit the file and restart the server.

Recent OpenProject versions allow several API tokens in parallel, so you can rotate with zero
downtime: create the new token, switch your clients over, then revoke the old one.

## Configuration

Configuration is entirely environment-driven. The table below is the authoritative reference:
the server binds **exactly these 25 names and no others**. Bare, unprefixed names such as
`READ_TIMEOUT` or `API_KEY` are deliberately ignored (a stray variable in your shell cannot
change or break the server), as is any other unknown variable. A `.env` file in the server's
working directory is read with the same names; real environment variables take precedence.
From-source users can start from
[`.env.example`](https://github.com/kar-thik/openproject-mcp/blob/main/.env.example).

| Variable | Default | Purpose |
|---|---|---|
| `OPENPROJECT_URL` | — (required) | Instance root URL, e.g. `https://openproject.example.com`. A trailing `/api/v3` is tolerated and stripped. |
| `OPENPROJECT_API_KEY` | — (required*) | API key from **My account → Access tokens**. Sent as HTTP Basic `apikey:<token>`. |
| `OPENPROJECT_OAUTH_TOKEN` | u