OpenProject MCP Server

<!-- mcp-name: io.github.kar-thik/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 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).

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.

| 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 | unset | OAuth bearer token, as an alternative to the API key. *One of the two credentials is required. | | OPENPROJECT_MCP_ACCEPT_LANGUAGE | unset | Sent as the Accept-Language header; OpenProject localizes validation messages accordingly. | | OPENPROJECT_MCP_CA_BUNDLE | system trust store | Path to a CA bundle (PEM) for instances behind a private CA. TLS is always verified; there is deliberately no off switch. | | OPENPROJECT_MCP_READ_ONLY | false | Serve read tools only: every write, destructive and admin tool is removed at startup. | | OPENPROJECT_MCP_ADMIN_TOOLS | false | Expose the three admin-gated membership write tools (hidden by default). | | OPENPROJECT_MCP_DISABLE | empty | Comma-separated group tags to remove whole tool groups at startup (see below). | | OPENPROJECT_MCP_PROFILE | full | core hides the module-backed groups at startup; a session can bring one back with enable_tool_group (see below). | | OPENPROJECT_MCP_INSECURE | false | Allow --transport http to start without auth tokens. Local development only. | | OPENPROJECT_MCP_DOWNLOAD_DIR | ./openproject-downloads | Directory where download_attachment writes files (created if missing; default is relative to the server's working directory). | | OPENPROJECT_MCP_MAX_DOWNLOAD_MB | 100 | Size cap for attachment downloads, in MiB. | | OPENPROJECT_MCP_CACHE_TTL | 300 | TTL in seconds for the metadata cache (statuses, types, priorities, schemas). | | OPENPROJECT_MCP_LOG_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR or CRITICAL (case-insensitive). | | OPENPROJECT_MCP_LOG_FORMAT | text | text or json. Logs always go to stderr (stdout belongs to the stdio transport). | | OPENPROJECT_MCP_LOG_BODIES | false | Log request/response bodies — only at DEBUG level, with credentials redacted. Development use only. | | OPENPROJECT_MCP_OTEL | false | Reserved for OpenTelemetry tracing. Accepted but not yet wired to anything in this release; setting it