OpenProject

OpenProject MCP Server

An MCP (Model Context Protocol) server for the OpenProject API v3. It gives Claude and any other MCP client 91 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 4.x and httpx (HTTP/2); speaks MCP 2026-07-28 and the earlier handshake versions.

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).

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.

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.

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 and 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, no install step:

uvx openproject-mcp-server

Or install persistently:

uv tool install openproject-mcp-server

or

pip install openproject-mcp-server

The minimal configuration is two environment variables:

export OPENPROJECT_URL=https://openproject.example.com

export OPENPROJECT_API_KEY=your-api-key

Validate the configuration without starting the server:

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

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):

{

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

From source

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:

  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:

  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 26 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.

| OPENPROJECT_MCP_MAX_INLINE_MB | 10 | Size cap for attachment bytes returned inl