{
  "markdown": "# OpenProject MCP Server\n\n<!-- mcp-name: io.github.kar-thik/openproject-mcp-server -->\n\n[![PyPI](https://img.shields.io/pypi/v/openproject-mcp-server)](https://pypi.org/project/openproject-mcp-server/)\n[![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)\n[![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)\n\nAn MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) server for the\n[OpenProject](https://www.openproject.org/) API v3. It gives Claude and any other MCP client\n88 tools covering work packages, comments and relations, attachments, git/PR activity, projects,\nsaved queries, notifications, time tracking, versions, people and memberships, meetings, news,\ndocuments, budgets and reporting — plus 4 report/workflow prompts and 3 resource templates.\nBuilt on FastMCP 3.x and httpx (HTTP/2).\n\nThis project is aimed at the OpenProject **Community edition**. OpenProject's Enterprise\nedition now ships with its own built-in MCP integration; this server brings the same\ncapability to self-hosted Community instances. It runs fine against any edition — it only\nneeds the public API v3.\n\nDesign principles, all enforced in code:\n\n- **Structured everything.** Every tool returns a typed model, so clients get an\n  `outputSchema` and machine-readable `structuredContent`, not prose. Errors come back as a\n  JSON envelope with a stable `type`, the upstream `http_status`, a `message` and a `hint`\n  describing how to correct the call.\n- **Honest degradation.** OpenProject instances differ by version, installed modules and\n  permissions. Tools report what they could not see as in-band notes — a missing module yields\n  an empty page with an explanation, never a fake success or a bare traceback.\n- **Safe by default.** A read-only mode, admin-gated membership writes, per-group tool\n  disabling, a `confirm=true` guard on every destructive tool, TLS always verified, and\n  credentials that never appear in logs.\n- **Version-adaptive.** Targets OpenProject 14 LTS through 17.x; API differences are detected\n  by a lazy, cached feature probe instead of assumptions (see\n  [Supported OpenProject versions](#supported-openproject-versions)).\n\n## What it looks like\n\nTwo exchanges against a fictional \"Website Relaunch\" project — every id, name and date below\nis invented. You describe the outcome; the model picks the tools, and what comes back to it\nis a typed object rather than prose to re-parse.\n\n```text\nYou         What is still open in Website Relaunch and due by Friday? The checkout\n            bug is urgent — raise it and leave a note for whoever owns it.\n\n  →  list_work_packages(project=\"website-relaunch\", status_scope=\"open\",\n                        due_before=\"2026-03-13\", sort_by=[[\"due_date\", \"asc\"]])\n\n     { \"items\": [\n         { \"id\": 4821, \"subject\": \"Checkout fails on expired coupon codes\",\n           \"type\": {\"id\": 7, \"name\": \"Bug\"}, \"status\": {\"id\": 7, \"name\": \"In progress\"},\n           \"assignee\": {\"id\": 118, \"name\": \"Dana Okafor\"}, \"due_date\": \"2026-03-11\" },\n         { \"id\": 4830, \"subject\": \"Move press-kit assets to the new CDN\",\n           \"type\": {\"id\": 1, \"name\": \"Task\"}, \"status\": {\"id\": 1, \"name\": \"New\"},\n           \"assignee\": null, \"due_date\": \"2026-03-13\" }],\n       \"pagination\": {\"total\": 2, \"page\": 1, \"page_size\": 20, \"has_more\": false} }\n\n  →  update_work_package(id=4821, priority=\"High\")\n  →  add_work_package_comment(id=4821, comment=\"Raised to High — it blocks the\n                              launch checklist. Dana, can you take a look today?\")\n\nAssistant   Two open items are due by Friday. #4821 is High now and the note is on\n            its thread; #4830 is due Friday and still has nobody on it.\n```\n\nThe rows above are abridged: each one also carries `priority`, `project`, `start_date`,\n`percentage_done` and `updated_at`, and the envelope keeps `groups`, `sums` and `notes` slots\nfor the calls that fill them.\n\nThe prompt templates cut out the tool round trips: the server reads OpenProject itself and\nhands back a finished document rather than instructions to go and fetch one. It arrives\nprefaced with a note that the numbers are already computed and must not be recomputed or\nembellished.\n\n```text\nYou         /weekly_report project=website-relaunch\n\n            # WEEKLY REPORT - AGILE SCRUM\n\n            _Generated from live OpenProject data_\n            ...\n            ## B. EXECUTIVE SUMMARY\n\n            **Progress against the sprint goal:** Not assessed — sprint goal and completion dates are not available\n\n            **Currently closed work updated in the window:**\n            1. #4802 - Ship the new pricing page\n            2. #4795 - Halve the hero image payload\n            ...\n            ### Data notes\n\n            - open/closed bucketing uses each status's isClosed flag from\n              GET /statuses, not status names; a status this instance renamed\n              or translated is still bucketed correctly\n```\n\nThat last block is the house style: a report says which of its numbers are partial, and a\ntool that could not read something returns the gap as a note instead of guessing. The whole\nsurface is in [Tools](#tools) and [Prompts and resources](#prompts-and-resources).\n\n## Requirements\n\n- Python >= 3.12\n- An OpenProject instance, version 14 LTS through 17.x (any edition; aimed at Community —\n  Enterprise ships its own MCP integration)\n- An OpenProject API key: in OpenProject, go to **My account → Access tokens** and generate an\n  API token\n\n## Installation\n\nThe distribution name is `openproject-mcp-server`. It installs two identical console scripts,\n`openproject-mcp-server` and `openproject-mcp`; the long form is canonical (an unrelated PyPI\npackage also installs a bin named `openproject-mcp`).\n\nRun one-shot with [uv](https://docs.astral.sh/uv/), no install step:\n\n```sh\nuvx openproject-mcp-server\n```\n\nOr install persistently:\n\n```sh\nuv tool install openproject-mcp-server\n# or\npip install openproject-mcp-server\n```\n\nThe minimal configuration is two environment variables:\n\n```sh\nexport OPENPROJECT_URL=https://openproject.example.com\nexport OPENPROJECT_API_KEY=your-api-key\n```\n\nValidate the configuration without starting the server:\n\n```sh\nopenproject-mcp-server --check\n```\n\n`--check` verifies the configuration and exits; it does not contact your instance. Once\nconnected through a client, call the `get_instance_info` tool for a live end-to-end check.\nWhen configuration is missing or invalid, the server prints the specific problems to stderr\nand exits with code 2 — never a traceback.\n\n### Claude Code\n\n```sh\nclaude mcp add openproject \\\n  --env OPENPROJECT_URL=https://openproject.example.com \\\n  --env OPENPROJECT_API_KEY=your-api-key \\\n  -- uvx openproject-mcp-server\n```\n\n### Claude Desktop and other MCP clients\n\nAdd to `claude_desktop_config.json` (or your client's equivalent `mcpServers` config):\n\n```json\n{\n  \"mcpServers\": {\n    \"openproject\": {\n      \"command\": \"uvx\",\n      \"args\": [\"openproject-mcp-server\"],\n      \"env\": {\n        \"OPENPROJECT_URL\": \"https://openproject.example.com\",\n        \"OPENPROJECT_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### From source\n\n```sh\ngit clone https://github.com/kar-thik/openproject-mcp\ncd openproject-mcp\nuv sync\nuv run openproject-mcp-server\n```\n\n## Updating or rotating your API token\n\nWhen a token is regenerated, revoked or invalidated (OpenProject major upgrades can do this —\nthe symptom is every tool suddenly failing with `authentication_failed` / HTTP 401), generate\na fresh one in OpenProject under **My account → Access tokens** and update it wherever your\nkey lives:\n\n- **Shell environment (easiest to rotate).** The server reads `OPENPROJECT_API_KEY` straight\n  from the OS environment, so you can export it globally — e.g. in `~/.zshenv` — and register\n  the server with no `--env` flags at all:\n\n  ```sh\n  claude mcp add openproject -- uvx openproject-mcp-server\n  ```\n\n  Rotation is then: edit the export, open a fresh terminal, reconnect. The client config\n  never contains a secret. (This does not work for GUI apps like Claude Desktop, which don't\n  read your shell profile.)\n- **Claude Code with `--env`.** The registration stores the key, so replace it:\n\n  ```sh\n  claude mcp remove openproject\n  claude mcp add openproject \\\n    --env OPENPROJECT_URL=https://openproject.example.com \\\n    --env OPENPROJECT_API_KEY=new-key \\\n    -- uvx openproject-mcp-server\n  ```\n\n  Then reconnect via `/mcp` (a running session keeps the old environment until it does).\n- **Claude Desktop and other JSON-configured clients.** Edit the `OPENPROJECT_API_KEY` value\n  in the client config and restart the client.\n- **`.env` file.** Edit the file and restart the server.\n\nRecent OpenProject versions allow several API tokens in parallel, so you can rotate with zero\ndowntime: create the new token, switch your clients over, then revoke the old one.\n\n## Configuration\n\nConfiguration is entirely environment-driven. The table below is the authoritative reference:\nthe server binds **exactly these 25 names and no others**. Bare, unprefixed names such as\n`READ_TIMEOUT` or `API_KEY` are deliberately ignored (a stray variable in your shell cannot\nchange or break the server), as is any other unknown variable. A `.env` file in the server's\nworking directory is read with the same names; real environment variables take precedence.\nFrom-source users can start from\n[`.env.example`](https://github.com/kar-thik/openproject-mcp/blob/main/.env.example).\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `OPENPROJECT_URL` | — (required) | Instance root URL, e.g. `https://openproject.example.com`. A trailing `/api/v3` is tolerated and stripped. |\n| `OPENPROJECT_API_KEY` | — (required*) | API key from **My account → Access tokens**. Sent as HTTP Basic `apikey:<token>`. |\n| `OPENPROJECT_OAUTH_TOKEN` | unset | OAuth bearer token, as an alternative to the API key. *One of the two credentials is required. |\n| `OPENPROJECT_MCP_ACCEPT_LANGUAGE` | unset | Sent as the `Accept-Language` header; OpenProject localizes validation messages accordingly. |\n| `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. |\n| `OPENPROJECT_MCP_READ_ONLY` | `false` | Serve read tools only: every write, destructive and admin tool is removed at startup. |\n| `OPENPROJECT_MCP_ADMIN_TOOLS` | `false` | Expose the three admin-gated membership write tools (hidden by default). |\n| `OPENPROJECT_MCP_DISABLE` | empty | Comma-separated group tags to remove whole tool groups at startup (see below). |\n| `OPENPROJECT_MCP_INSECURE` | `false` | Allow `--transport http` to start without auth tokens. Local development only. |\n| `OPENPROJECT_MCP_DOWNLOAD_DIR` | `./openproject-downloads` | Directory where `download_attachment` writes files (created if missing; default is relative to the server's working directory). |\n| `OPENPROJECT_MCP_MAX_DOWNLOAD_MB` | `100` | Size cap for attachment downloads, in MiB. |\n| `OPENPROJECT_MCP_CACHE_TTL` | `300` | TTL in seconds for the metadata cache (statuses, types, priorities, schemas). |\n| `OPENPROJECT_MCP_LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL` (case-insensitive). |\n| `OPENPROJECT_MCP_LOG_FORMAT` | `text` | `text` or `json`. Logs always go to stderr (stdout belongs to the stdio transport). |\n| `OPENPROJECT_MCP_LOG_BODIES` | `false` | Log request/response bodies — only at DEBUG level, with credentials redacted. Development use only. |\n| `OPENPROJECT_MCP_OTEL` | `false` | Reserved for OpenTelemetry tracing. Accepted but not yet wired to anything in this release; setting it produces no traces. |\n| `OPENPROJECT_MCP_HTTP_HOST` | `127.0.0.1` | Bind address for `--transport http`. |\n| `OPENPROJECT_MCP_HTTP_PORT` | `8000` | Port for `--transport http`. |\n| `OPENPROJECT_MCP_AUTH_TOKENS` | unset | Comma-separated bearer tokens accepted by `--transport http` (e.g. one per client). Every request must carry `Authorization: Bearer <token>` with one of them; anything else gets a 401. Without it (and without `OPENPROJECT_MCP_INSECURE=1`), the HTTP transport refuses to start. See [Transports](#transports). |\n| `OPENPROJECT_MCP_CONNECT_TIMEOUT` | `10` | Seconds to wait for a TCP/TLS connection to OpenProject. |\n| `OPENPROJECT_MCP_READ_TIMEOUT` | `30` | Seconds to wait for response data. |\n| `OPENPROJECT_MCP_WRITE_TIMEOUT` | `60` | Seconds to wait while sending request data (uploads). |\n| `OPENPROJECT_MCP_POOL_TIMEOUT` | `5` | Seconds to wait for a free connection from the pool. |\n| `OPENPROJECT_MCP_MAX_CONNECTIONS` | `10` | Connection pool size toward OpenProject. |\n| `OPENPROJECT_MCP_MAX_RETRIES` | `3` | Retry budget for idempotent requests. |\n\nSecrets (`OPENPROJECT_API_KEY`, `OPENPROJECT_OAUTH_TOKEN`, `OPENPROJECT_MCP_AUTH_TOKENS`) are\nheld in memory as Pydantic `SecretStr` values and are never written to logs; the\n`Authorization` header is redacted in every log record.\n\n### Limiting what the model can do\n\nThree settings shrink the tool surface at startup (the tool list is fixed for the lifetime of\nthe process):\n\n- `OPENPROJECT_MCP_READ_ONLY=1` serves only the 39 read tools.\n- `OPENPROJECT_MCP_ADMIN_TOOLS=1` reveals the three membership write tools\n  (`create_membership`, `update_membership`, `delete_membership`); they are hidden by default.\n- `OPENPROJECT_MCP_DISABLE` drops whole groups to cut prompt cost, e.g.\n  `OPENPROJECT_MCP_DISABLE=meetings,news`. The valid group tags are:\n  `work_packages`, `wp_collaboration`, `attachments`, `git_activity`, `projects`, `queries`,\n  `notifications`, `time_entries`, `versions`, `people`, `metadata`, `meetings`, `wiki`,\n  `documents`, `budgets`, `news`, `reporting` — the same tags that head each section of the\n  tool catalog below.\n\nIndependent of all three, every destructive tool (the 13 permanent deletes) requires an\nexplicit `confirm=true` argument before it acts.\n\n## Transports\n\n- **stdio** (default) — what Claude Code, Claude Desktop and most local MCP clients use.\n  Logs go to stderr; stdout carries only the protocol.\n- **Streamable HTTP** — `openproject-mcp-server --transport http`. Binds `127.0.0.1:8000` by\n  default; override with `--host`/`--port` or `OPENPROJECT_MCP_HTTP_HOST`/\n  `OPENPROJECT_MCP_HTTP_PORT`. The HTTP transport refuses to start without authentication\n  configured: set `OPENPROJECT_MCP_AUTH_TOKENS` to a comma-separated list of bearer tokens,\n  or — for local development only — set `OPENPROJECT_MCP_INSECURE=1`.\n\n  With tokens configured, every HTTP request to the MCP endpoint must carry an\n  `Authorization: Bearer <token>` header whose token matches one of the configured values\n  (compared in constant time); requests with a missing, malformed or unknown token are\n  rejected with a 401 and a `WWW-Authenticate` header. Multiple tokens are supported —\n  for example one per client, so each can be revoked independently. Tokens must be ASCII,\n  and the endpoint applies no rate limiting, so use long random values — for example\n  `python -c \"import secrets; print(secrets.token_urlsafe(32))\"`.\n  `OPENPROJECT_MCP_INSECURE=1` remains a development-only escape hatch that leaves the\n  endpoint open without authentication.\n\n  The server does not terminate TLS, so tokens would otherwise cross the network in\n  plaintext: keep the default `127.0.0.1` bind, and if you must expose the HTTP transport\n  beyond localhost, put it behind a TLS-terminating reverse proxy (for example nginx or\n  Caddy).\n\n## Tools\n\n88 tools: 39 read, 46 write and 3 admin-gated writes. The admin tools stay hidden unless\n`OPENPROJECT_MCP_ADMIN_TOOLS=1`; the 13 destructive tools additionally require `confirm=true`\non every call. Each section heading names the group tag accepted by\n`OPENPROJECT_MCP_DISABLE`.\n\n### Work packages (`work_packages`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `search_work_packages` | Read | Find work packages by text when you do not know their ids. |\n| `list_work_packages` | Read | List work packages with structured filters — the workhorse read tool. |\n| `get_work_package` | Read | Read one work package in full: description, dates, custom fields, parent and progress. |\n| `create_work_package` | Write | Create a work package, validated through OpenProject's own form endpoint first. |\n| `update_work_package` | Write | Change any writable field of a work package, with optimistic locking. |\n| `bulk_update_work_packages` | Write | Preview or apply up to 50 updates with per-item diffs, validation and conflict results. |\n| `delete_work_package` | Write (destructive) | Permanently delete a work package and everything attached to it. |\n\nBatch workflow: call `bulk_update_work_packages(updates=[{\"id\": 4821,\n\"changes\": {\"target_versions\": [3, 4]}}])` to preview. Review the returned changes,\nthen repeat with `dry_run=false` and each item's returned `lock_version` included\nin `updates`. Any preflight error prevents the whole batch from writing. A later\nconflict can produce partial success; inspect every item and never replay successful\nupdates. `unknown` means the write may have committed before the response was lost.\n\n### Comments, relations, watchers, reminders (`wp_collaboration`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_work_package_comments` | Read | Read the comment thread and change history of a work package. |\n| `add_work_package_comment` | Write | Post a comment on a work package. |\n| `edit_work_package_comment` | Write | Rewrite the text of an existing work-package comment. |\n| `add_work_package_watcher` | Write | Subscribe a user to a work package's notifications. |\n| `remove_work_package_watcher` | Write | Unsubscribe a user from a work package's notifications. |\n| `create_work_package_relation` | Write | Link two work packages (blocks, follows, duplicates, relates, ...). |\n| `update_work_package_relation` | Write | Change an existing relation's type, lag or description. |\n| `delete_work_package_relation` | Write (destructive) | Remove the link between two work packages. |\n| `toggle_comment_reaction` | Write | React to a work-package comment with an emoji, or take the reaction back. |\n| `set_work_package_reminder` | Write | Set, change or clear your personal reminder on a work package. |\n| `list_reminders` | Read | List your own upcoming work-package reminders. |\n| `execute_custom_action` | Write | Run an instance-defined one-click action on a work package. |\n\n### Attachments and file links (`attachments`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_attachments` | Read | List the files attached to one container. |\n| `download_attachment` | Read | Download an attachment's bytes to a file on the machine running this server. |\n| `upload_attachment` | Write | Attach a local file to a work package, wiki page, meeting, document, budget or comment. |\n| `delete_attachment` | Write (destructive) | Permanently delete one attached file from OpenProject. |\n| `list_file_links` | Read | List the external-storage files (Nextcloud, OneDrive/SharePoint) linked to a work package. |\n\n### Git and pull requests (`git_activity`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `get_work_package_git_activity` | Read | Show the code behind a work package: commits, pull/merge requests and CI status. |\n| `get_github_pull_request` | Read | Read one linked GitHub pull request in full, including its CI check runs. |\n\n### Projects (`projects`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_projects` | Read | List projects, filtered server-side, one page at a time. |\n| `get_project` | Read | Read one project in full. |\n| `create_project` | Write | Create a project, validated through OpenProject's own form endpoint first. |\n| `update_project` | Write | Change a project's name, description, visibility, parent, status or archived state. |\n| `delete_project` | Write (destructive) | Schedule the permanent deletion of a project and everything inside it. |\n| `copy_project` | Write | Copy a project — its settings, and optionally its work packages — into a new one. |\n| `get_job_status` | Read | Check whether a background job (a project copy, a scheduled deletion) has finished. |\n| `set_project_favorite` | Write | Add or remove a project from the authenticated user's favorites (OpenProject 17+). |\n| `list_project_phase_definitions` | Read | List the instance-wide phase catalog (Initiating, Planning, ...) with start/finish gates (OpenProject 16.1+). |\n| `get_project_phase` | Read | Read one project's phase record; ids come from a work package's `project_phase` reference. |\n\n### Saved queries (`queries`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_queries` | Read | List the saved work-package views (queries) this user can open. |\n| `run_query` | Read | Run a saved view and get its work packages as they are right now. |\n| `save_query` | Write | Save a filter set as a reusable OpenProject view the whole team can open. |\n\n### Notifications (`notifications`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_notifications` | Read | Read the authenticated user's OpenProject inbox. |\n| `mark_notifications` | Write | Mark specific notifications read (or unread) in one bulk request. |\n| `mark_all_notifications_read` | Write | Mark everything matching the filters as read — the whole inbox by default. |\n\n### Time tracking (`time_entries`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_time_entries` | Read | List logged time, filtered server-side, with an optional accurate total. |\n| `log_time` | Write | Book time against a work package or a project. |\n| `update_time_entry` | Write | Correct an existing time entry. |\n| `delete_time_entry` | Write (destructive) | Permanently delete a logged time entry. |\n\n### Versions and sprints (`versions`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_versions` | Read | List versions (releases, milestones, sprints) you can assign work packages to. |\n| `create_version` | Write | Create a version (release, milestone or sprint) inside a project. |\n| `update_version` | Write | Change a version's name, dates, description, status or sharing. |\n| `delete_version` | Write (destructive) | Permanently delete a version. |\n\n### People and memberships (`people`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `search_principals` | Read | Find users, groups and placeholder users, and get their ids. |\n| `get_user` | Read | Read one user's profile: name, login, email, admin flag and status. |\n| `list_memberships` | Read | List who has access to which project, and with which roles. |\n| `create_membership` | Admin write | Grant a principal one or more roles in a project. |\n| `update_membership` | Admin write | Replace the roles of an existing membership. |\n| `delete_membership` | Admin write (destructive) | Revoke a principal's access to a project. |\n| `list_roles` | Read | List the roles this instance defines, with their ids. |\n\nThe three membership write tools require `OPENPROJECT_MCP_ADMIN_TOOLS=1` (and an OpenProject\naccount with the Manage members permission).\n\n### Instance metadata and schemas (`metadata`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `get_instance_info` | Read | Check the OpenProject connection and report what this instance supports. |\n| `get_project_metadata` | Read | List the ids and names (types, statuses, priorities, ...) that are actually valid on this instance. |\n| `get_work_package_schema` | Read | Show which fields a work package of this type accepts in this project. |\n| `list_permissions` | Read | List what the authenticated user is allowed to do, globally or in one project. |\n\n### Meetings (`meetings`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_meetings` | Read | List meetings: what is coming up, what already ran. |\n| `get_meeting` | Read | Read one meeting in full: participants, the agenda, and any recorded outcomes. |\n| `create_meeting` | Write | Schedule a meeting in a project and optionally invite participants. |\n| `update_meeting` | Write | Change a meeting's title, time, place or invite list — or move its lifecycle state. |\n| `delete_meeting` | Write (destructive) | Permanently delete a meeting, together with its agenda and recorded outcomes. |\n| `add_meeting_agenda_item` | Write | Add one item to a meeting's agenda, optionally pinned to a work package. |\n| `update_meeting_agenda_item` | Write | Edit one agenda item: retitle it, rewrite its notes, retime, reorder or re-link it. |\n| `delete_meeting_agenda_item` | Write (destructive) | Permanently delete one agenda item, with any outcomes recorded against it. |\n| `add_meeting_outcome` | Write | Record an outcome — a decision, a note, a follow-up ticket — against an agenda item. |\n| `update_meeting_outcome` | Write | Correct a recorded outcome's kind, text or linked work package. |\n| `delete_meeting_outcome` | Write (destructive) | Permanently delete a recorded outcome from a running meeting's minutes. |\n| `list_recurring_meetings` | Read | List recurring meeting series — the repetition rules, not the individual meetings. |\n| `get_recurring_meeting` | Read | Read one recurring series in full: the schedule plus its next occurrences. |\n| `create_recurring_meeting` | Write | Create a recurring meeting series: a schedule plus a template the occurrences copy. |\n| `delete_recurring_meeting` | Write (destructive) | Permanently delete a recurring series: template, schedule, and every occurrence. |\n| `init_recurring_meeting_occurrence` | Write | Materialize one occurrence of a series as a real meeting, copied from the template. |\n| `cancel_recurring_meeting_occurrence` | Write (destructive) | Cancel one occurrence of a series — skip a slot without touching the schedule. |\n\n### Wiki (`wiki`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `get_wiki_page` | Read | Read a wiki page's identity and project — not its content (API v3 does not expose page bodies). |\n\n### Documents (`documents`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_documents` | Read | List the documents visible to you, across every project. |\n| `get_document` | Read | Read one document with its full description text. |\n\n### Budgets (`budgets`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_budgets` | Read | List a project's budgets — their ids and names, which is all API v3 exposes. |\n\n### News (`news`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `list_news` | Read | List project news — the announcements a team publishes on its project overview. |\n| `get_news` | Read | Read one news entry in full, including the markdown body. |\n| `create_news` | Write | Publish a news announcement in a project. |\n| `update_news` | Write | Correct or rewrite a published news entry. |\n| `delete_news` | Write (destructive) | Permanently delete a news entry. |\n\n### Reporting (`reporting`)\n\n| Tool | Kind | What it does |\n|---|---|---|\n| `get_project_report_data` | Read | Aggregate everything a status report needs about one project and one date window. |\n\n## Prompts and resources\n\nReport data uses `closed_updated` for currently closed work updated in the requested\nwindow. This replaces the former `closed` field in v0.3.0. It does not establish when\nwork was completed; sprint health remains unassessed without supporting data.\n\nFour prompt templates render live OpenProject data into ready-to-use briefings:\n\n- **weekly_report** — a weekly status report for one project: currently closed and updated / in progress / planned,\n  hours and impediments.\n- **daily_standup** — today's standup for one project: yesterday's movement, what is due\n  today, and what is blocked.\n- **triage_inbox** — groups your unread notifications by reason and suggests actions.\n- **groom_backlog** — sweeps a project's open backlog for unassigned, stale and unestimated\n  work.\n\nThree resource templates expose OpenProject objects at stable URIs:\n\n- `openproject://work_package/{id}` — one work package as JSON.\n- `openproject://project/{identifier}` — one project as JSON (identifier slug or numeric id).\n- `openproject://attachment/{id}` — the attachment's bytes with the detected MIME type.\n\n## Supported OpenProject versions\n\nThe server targets OpenProject **14 LTS through 17.x**. Instead of assuming one API dialect,\nit probes the instance lazily on first need and caches the result for an hour. The\nversion-dependent surfaces:\n\n- **Target versions**: work-package details expose `target_versions` on every supported\n  instance. Create/update accept a list of version ids (`[]` clears); the schema selects\n  `targetVersions` on 17.8+ or a single legacy `version`. The old `version` argument remains\n  a single-value alias; do not pass both. On reads it is null for multiple assignments.\n- **Internal (private) comments** need OpenProject >= 16. Older servers silently ignore the\n  internal flag, so below 16 the server refuses with a clear error rather than posting a\n  comment publicly that you asked to keep internal.\n- **Emoji reactions** (`toggle_comment_reaction`) need OpenProject >= 16; detected from the\n  version, tolerant of a 404 at call time.\n- **Project favorites** (`set_project_favorite`) need OpenProject >= 17; same tolerance.\n- **Time-entry filters**: the work-package filter is probed (`entityId`, falling back to the\n  pre-15.x `workPackage` spelling).\n- **Permission contexts** (`list_permissions`): the context prefix is probed (`p{id}`, falling\n  back to the `w{id}` spelling introduced in 17.2).\n- **Meetings time filter**: OpenProject 17.6 changed the wire dialect; `list_meetings`\n  discovers which spelling the instance accepts and caches it.\n\nFeatures that depend on optional instance modules (meetings, news, documents, budgets, wiki,\nbacklogs, GitHub/GitLab integration, external storages) degrade honestly when the module is\nabsent: list tools return an empty page with an in-band note naming the missing module, and\ndetail tools return a structured error explaining both possible readings of the 404.\n\n## Security\n\n- The API key and OAuth token are held as `SecretStr` and never logged; `Authorization` and\n  cookie headers are redacted from every log record. Request/response bodies are only logged\n  at DEBUG level with `OPENPROJECT_MCP_LOG_BODIES=1`, for development.\n- The `Authorization` header is stripped whenever a redirect leaves the OpenProject origin —\n  attachment downloads redirect to presigned object-storage URLs, and the credential must not\n  travel there.\n- TLS is always verified. Private CAs are supported via `OPENPROJECT_MCP_CA_BUNDLE`; an\n  insecure-TLS switch deliberately does not exist.\n- Attachment downloads respect OpenProject's virus scanner: quarantined files are never\n  fetched and produce a structured `attachment_quarantined` error. Downloads are capped by\n  `OPENPROJECT_MCP_MAX_DOWNLOAD_MB`, stored under sanitized file names (directory separators\n  and traversal sequences are neutralized), and reported with a SHA-256 of the bytes.\n- Destructive tools require `confirm=true` and are annotated so clients can ask the user\n  first.\n- The HTTP transport refuses to start without `OPENPROJECT_MCP_AUTH_TOKENS` configured and\n  verifies the `Authorization: Bearer` header on every request — missing or invalid tokens\n  are rejected with a 401, and token comparison is constant-time. The server does not\n  terminate TLS: keep the default `127.0.0.1` bind, and put a TLS-terminating reverse proxy\n  in front if the port must be reachable from anywhere else (see [Transports](#transports)).\n\n## Troubleshooting\n\n| Symptom | What it means and what to do |\n|---|---|\n| Server exits with \"cannot start, configuration is incomplete\" | Run `openproject-mcp-server --check` and fix the problems it lists; the variable reference is the [Configuration](#configuration) section above. |\n| 401 authentication_failed | The API key is wrong, revoked, or belongs to a blocked account. Generate a fresh token under **My account → Access tokens**. |\n| 403 permission_denied | The account is authenticated but lacks a role permission for that project, or the relevant module is disabled for it. |\n| Empty list plus a note about a missing module | That OpenProject module (meetings, news, documents, ...) is not installed or not enabled in the project — the empty result is the honest answer, not an error. |\n| TLS certificate errors | Your instance uses a private CA: point `OPENPROJECT_MCP_CA_BUNDLE` at its PEM bundle. There is no option to disable verification. |\n| `--transport http` refuses to start | Set `OPENPROJECT_MCP_AUTH_TOKENS` (comma-separated bearer tokens), or `OPENPROJECT_MCP_INSECURE=1` for local development only — see [Transports](#transports). |\n| 401 from the MCP HTTP endpoint itself | The request's `Authorization: Bearer <token>` header is missing or does not match any configured `OPENPROJECT_MCP_AUTH_TOKENS` entry. Check the client's token for typos; distinct from the upstream `401 authentication_failed` above, which is about the OpenProject API key. |\n| Proxies | Standard `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` variables are honored by the underlying HTTP client. |\n\nWhen reporting an issue, please include your OpenProject version, the output of\n`openproject-mcp-server --version`, and the output of `openproject-mcp-server --check`.\n\n## Development\n\n```sh\ngit clone https://github.com/kar-thik/openproject-mcp\ncd openproject-mcp\nuv sync --group dev\nuv run pytest              # entire suite runs offline (respx-mocked HTTP), no instance needed\nuv run ruff check .\nuv run ruff format --check .\nuv run pyright             # strict mode\n```\n\nThe default suite stays offline. Opt-in compatibility checks run against fresh official\nOpenProject 14.6, 15.5, 16.6 and 17.8 containers in the Compatibility workflow\n(including both single- and multiple-version modes on 17.8). To run one\nlocally with Docker running:\n\n```sh\nuv run python scripts/live_smoke.py --image openproject/openproject:17.8.0\n```\n\nThe harness seeds a private project, temporary users, custom fields and versions; it tests\nthrough MCP, then removes the container and its volumes. Existing instances and credentials\nare not used. Direct pytest runs skip these tests unless `--live-openproject` is supplied\nwith a disposable fixture file. The\nfull technical specification lives in\n[SPEC.md](https://github.com/kar-thik/openproject-mcp/blob/main/SPEC.md).\n\nReleasing is documented in\n[CONTRIBUTING.md](https://github.com/kar-thik/openproject-mcp/blob/main/CONTRIBUTING.md).\n\n## License and trademark\n\nMIT — see [LICENSE](https://github.com/kar-thik/openproject-mcp/blob/main/LICENSE).\n\nThis is a community project. It is not affiliated with, endorsed by, or supported by\nOpenProject GmbH. \"OpenProject\" is a trademark of OpenProject GmbH and is used here only to\nindicate interoperability.\n",
  "bytes": 34893,
  "sha": "49ab0a3e034729128c4ea27fee111044260a0e2ccc003989d6d3fe1181a6f9aa",
  "repo_slug": "kar-thik/openproject-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kar_thik_openproject_mcp_serve_9124e358/readme"
}