OpenProject MCP Server

OpenProject MCP Server

An MCP (Model Context Protocol) server for theOpenProject API v3. It gives Claude and any other MCP client72 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 Enterpriseedition now ships with its own built-in MCP integration; this server brings the samecapability to self-hosted Community instances. It runs fine against any edition — it onlyneeds the public API v3.

Design principles, all enforced in code:

• Structured everything. Every tool returns a typed model, so clients get anoutputSchema and machine-readable structuredContent, not prose. Errors come back as aJSON envelope with a stable type, the upstream http_status, a message and a hintdescribing how to correct the call.
• Honest degradation. OpenProject instances differ by version, installed modules andpermissions. Tools report what they could not see as in-band notes — a missing module yieldsan 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 tooldisabling, a confirm=true guard on every destructive tool, TLS always verified, andcredentials that never appear in logs.
• Version-adaptive. Targets OpenProject 14 LTS through 17.x; API differences are detectedby a lazy, cached feature probe instead of assumptions (seeSupported OpenProject versions).

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 anAPI 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 PyPIpackage 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. Onceconnected 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 stderrand 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), generatea fresh one in OpenProject under My account → Access tokens and update it wherever yourkey lives:

• Shell environment (easiest to rotate). The server reads OPENPROJECT_API_KEY straightfrom the OS environment, so you can export it globally — e.g. in ~/.zshenv — and registerthe 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 confignever contains a secret. (This does not work for GUI apps like Claude Desktop, which don'tread 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 valuein 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 zerodowntime: 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 asREAD_TIMEOUT or API_KEY are deliberately ignored (a stray variable in your shell cannotchange or break the server), as is any other unknown variable. A .env file in the server'sworking directory is read with the same names; real environment variables take precedence.From-source users can start from.env.example.

Secrets (OPENPROJECT_API_KEY, OPENPROJECT_OAUTH_TOKEN, OPENPROJECT_MCP_AUTH_TOKENS) areheld in memory as Pydantic SecretStr values and are never written to logs; theAuthorization header is redacted in every log record.

Limiting what the model can do

Three settings shrink the tool surface at startup (the tool list is fixed for the lifetime ofthe process):

• OPENPROJECT_MCP_READ_ONLY=1 serves only the 35 read tools.
• OPENPROJECT_MCP_ADMIN_TOOLS=1 reveals the three membership write tools(create_membership, update_membership, delete_membership); they are hidden by default.
• OPENPROJECT_MCP_DISABLE drops whole groups to cut prompt cost, e.g.OPENPROJECT_MCP_DISABLE=meetings,news. The valid group tags are:work_packages, wp_collaboration, attachments, git_activity, projects, queries,notifications, time_entries, versions, people, metadata, meetings, wiki,documents, budgets, news, reporting — the same tags that head each section of thetool catalog below.

Independent of all three, every destructive tool (the eight permanent deletes) requires anexplicit confirm=true argument before it acts.

Transports

• stdio (default) — what Claude Code, Claude Desktop and most local MCP clients use.Logs go to stderr; stdout carries only the protocol.

• Streamable HTTP — openproject-mcp-server --transport http. Binds 127.0.0.1:8000 bydefault; override with --host/--port or OPENPROJECT_MCP_HTTP_HOST/OPENPROJECT_MCP_HTTP_PORT. The HTTP transport refuses to start without authenticationconfigured: set OPENPROJECT_MCP_AUTH_TOKENS to a comma-separated list of bearer tokens,or — for local development only — set OPENPROJECT_MCP_INSECURE=1.

  With tokens configured, every HTTP request to the MCP endpoint must carry anAuthorization: Bearer <token> header whose token matches one of the configured values(compared in constant time); requests with a missing, malformed or unknown token arerejected with a 401 and a WWW-Authenticate header. Multiple tokens are supported —for example one per client, so each can be revoked independently. Tokens must be ASCII,and the endpoint applies no rate limiting, so use long random values — for examplepython -c "import secrets; print(secrets.token_urlsafe(32))".OPENPROJECT_MCP_INSECURE=1 remains a development-only escape hatch that leaves theendpoint open without authentication.

  The server does not terminate TLS, so tokens would otherwise cross the network inplaintext: keep the default 127.0.0.1 bind, and if you must expose the HTTP transportbeyond localhost, put it behind a TLS-terminating reverse proxy (for example nginx orCaddy).

Tools

72 tools: 35 read, 34 write and 3 admin-gated writes. The admin tools stay hidden unlessOPENPROJECT_MCP_ADMIN_TOOLS=1; the 8 destructive tools additionally require confirm=trueon every call. Each section heading names the group tag accepted byOPENPROJECT_MCP_DISABLE.

Work packages (work_packages)

Comments, relations, watchers, reminders (wp_collaboration)

Attachments and file links (attachments)

Git and pull requests (git_activity)

Projects (projects)

Saved queries (queries)

Notifications (notifications)

Time tracking (time_entries)

Versions and sprints (versions)

People and memberships (people)

The three membership write tools require OPENPROJECT_MCP_ADMIN_TOOLS=1 (and an OpenProjectaccount with the Manage members permission).

Instance metadata and schemas (metadata)

Meetings (meetings)

Wiki (wiki)

Documents (documents)

Budgets (budgets)

News (news)

Reporting (reporting)

Prompts and resources

Four prompt templates render live OpenProject data into ready-to-use briefings:

• weekly_report — a weekly status report for one project: done / in progress / planned,hours and impediments.
• daily_standup — today's standup for one project: yesterday's movement, what is duetoday, and what is blocked.
• triage_inbox — groups your unread notifications by reason and suggests actions.
• groom_backlog — sweeps a project's open backlog for unassigned, stale and unestimatedwork.

Three resource templates expose OpenProject objects at stable URIs:

• openproject://work_package/{id} — one work package as JSON.
• openproject://project/{identifier} — one project as JSON (identifier slug or numeric id).
• openproject://attachment/{id} — the attachment's bytes with the detected MIME type.

Supported OpenProject versions

The server targets OpenProject 14 LTS through 17.x. Instead of assuming one API dialect,it probes the instance lazily on first need and caches the result for an hour. Theversion-dependent surfaces:

• Internal (private) comments need OpenProject >= 16. Older servers silently ignore theinternal flag, so below 16 the server refuses with a clear error rather than posting acomment publicly that you asked to keep internal.
• Emoji reactions (toggle_comment_reaction) need OpenProject >= 16; detected from theversion, tolerant of a 404 at call time.
• Project favorites (set_project_favorite) need OpenProject >= 17; same tolerance.
• Time-entry filters: the work-package filter is probed (entityId, falling back to thepre-15.x workPackage spelling).
• Permission contexts (list_permissions): the context prefix is probed (p{id}, fallingback to the w{id} spelling introduced in 17.2).
• Meetings time filter: OpenProject 17.6 changed the wire dialect; list_meetingsdiscovers which spelling the instance accepts and caches it.

Features that depend on optional instance modules (meetings, news, documents, budgets, wiki,backlogs, GitHub/GitLab integration, external storages) degrade honestly when the module isabsent: list tools return an empty page with an in-band note naming the missing module, anddetail tools return a structured error explaining both possible readings of the 404.

Security

• The API key and OAuth token are held as SecretStr and never logged; Authorization andcookie headers are redacted from every log record. Request/response bodies are only loggedat DEBUG level with OPENPROJECT_MCP_LOG_BODIES=1, for development.
• The Authorization header is stripped whenever a redirect leaves the OpenProject origin —attachment downloads redirect to presigned object-storage URLs, and the credential must nottravel there.
• TLS is always verified. Private CAs are supported via OPENPROJECT_MCP_CA_BUNDLE; aninsecure-TLS switch deliberately does not exist.
• Attachment downloads respect OpenProject's virus scanner: quarantined files are neverfetched and produce a structured attachment_quarantined error. Downloads are capped byOPENPROJECT_MCP_MAX_DOWNLOAD_MB, stored under sanitized file names (directory separatorsand traversal sequences are neutralized), and reported with a SHA-256 of the bytes.
• Destructive tools require confirm=true and are annotated so clients can ask the userfirst.
• The HTTP transport refuses to start without OPENPROJECT_MCP_AUTH_TOKENS configured andverifies the Authorization: Bearer header on every request — missing or invalid tokensare rejected with a 401, and token comparison is constant-time. The server does notterminate TLS: keep the default 127.0.0.1 bind, and put a TLS-terminating reverse proxyin front if the port must be reachable from anywhere else (see Transports).

Troubleshooting

When reporting an issue, please include your OpenProject version, the output ofopenproject-mcp-server --version, and the output of openproject-mcp-server --check.

Development

git clone https://github.com/kar-thik/openproject-mcp
cd openproject-mcp
uv sync --group dev
uv run pytest              # entire suite runs offline (respx-mocked HTTP), no instance needed
uv run ruff check .
uv run ruff format --check .
uv run pyright             # strict mode

The suite currently contains no tests that need a live OpenProject instance; an opt-inintegration marker is registered and reserved for any that are added later. Thefull technical specification lives inSPEC.md.

Releasing is documented inCONTRIBUTING.md.

License and trademark

MIT — see LICENSE.

This is a community project. It is not affiliated with, endorsed by, or supported byOpenProject GmbH. "OpenProject" is a trademark of OpenProject GmbH and is used here only toindicate interoperability.