OpenProject CE MCP

An MCP server for OpenProject that lets local AI agents read and manage project data through structured, guarded tools.

The server runs as a local subprocess of your MCP client over stdio. It wraps OpenProject API v3 and exposes typed tools for projects, work packages, memberships, versions, boards, time entries, and more.

Scope: Community Edition

This MCP server targets OpenProject Community Edition only. It does not support Enterprise Edition features such as:

• Placeholder Users

• Budgets

• Portfolios

• Programs

• Custom Actions

• Baseline Comparisons

Note: OpenProject Enterprise Edition includes its own MCP server. If you have an Enterprise license, use the official Enterprise MCP instead of this one.

Related MCP server: projscan

Table of Contents

• What you can do

• How it works

• Getting started

• Configuration

• Tools

• Integrations

• Architecture

• Development

What you can do

Projects

• List, create, copy, update, and delete projects

• Read project configurations, lifecycle phases, and admin context

• Create, update, and delete memberships and versions; list roles

Work packages

• List and search work packages with structured filters

• Create, update, and delete work packages; create subtasks; create, update, and delete relations; add comments (no edit or delete)

• Upload and delete attachments; add and remove watchers; read activity logs

• Log, update, and delete time entries

Boards and views

• Create, read, update, and delete saved boards (queries); read views

Users and groups

• Read user accounts and group memberships

• Create, update, lock, unlock, and delete users; add and remove group members

Supporting data

• Fetch individual wiki pages by id; create, update, and delete news; read and update documents

• Read and mark notifications; read help texts, working days, and instance configuration

• Create and inspect grids; inspect custom options

All write operations follow a preview-then-confirm pattern by default: call a tool once to get a validated preview, then again with confirm=true to execute. This can be bypassed globally with OPENPROJECT_AUTO_CONFIRM_WRITE=true.

How it works

• Communicates with the MCP client over stdio — no remote server, no persistent storage

• Reads are enabled by default; writes require explicit opt-in via environment variables

• Create and update operations validate the payload against OpenProject form endpoints before writing; delete and other simple operations execute directly once confirmed

• Project scope is enforced server-side: the MCP only exposes what the configured allowlists permit

• Responses are bounded and paginated — compact summaries, not raw HAL payloads

Getting started

In short:

1. Install the server (the one-liner below).

2. Copy the command and env from the generated .mcp.json into your MCP client's config — or let the installer register a detected client for you.

3. Restart your client.

4. Verify by asking it to call list_projects.

The rest of this section covers each step in detail.

Requirements

uv is recommended for dependency management but not required.

Prepare your OpenProject instance

An administrator must enable API token creation once:

Administration → API and webhooks → API

To create a personal token: My account → Access tokens → + API token. Copy the token immediately — it is only shown once. Format: opapi-....

Install

Install from PyPI, then run the interactive setup. Pick whichever installer you already use:

# uv (recommended) — installs the openproject-ce-mcp command onto your PATH
uv tool install openproject-ce-mcp

# or pipx
pipx install openproject-ce-mcp

# or pip
pip install openproject-ce-mcp

Then configure it — this collects your OpenProject URL/token and permissions and writes the config:

openproject-ce-mcp configure

It asks two independent questions:

1. Configure globally (user-wide)? — registers the server in a detected client's user-wide config (e.g. ~/.claude.json), available in every project.

2. Configure project-scoped (this directory)? — writes config files into the current directory (.mcp.json, .codex/config.toml, .vscode/mcp.json, .cursor/mcp.json); offered for every supported client, whether or not it is detected. A generic .mcp.json you can copy values from is written too (unless you selected Claude Code, whose project config is .mcp.json).

Choose one or both; choosing neither aborts without writing anything (before it even asks for your token). Existing entries for other MCP servers are kept and each edited file is backed up first. After it writes, it tells you how to (re)load each client so the server actually starts.

Zero-install run: with uv you can skip installing entirely — point your client's command at uvx with args ["openproject-ce-mcp"]. See the per-client guides below.

The source installer clones the repo, installs dependencies (via uv if available, or venv + pip otherwise), and runs the same interactive setup.

Windows (PowerShell) — clones to %USERPROFILE%\openproject-ce-mcp, binary at ...\.venv\Scripts\openproject-ce-mcp.exe; set $env:DIR to override the destination:

irm https://raw.githubusercontent.com/jtauschl/openproject-ce-mcp/main/get.ps1 | iex

macOS / Linux — clones to ~/openproject-ce-mcp, binary at ~/openproject-ce-mcp/.venv/bin/openproject-ce-mcp; DIR=… overrides the destination:

curl -fsSL https://raw.githubusercontent.com/jtauschl/openproject-ce-mcp/main/get.sh | sh

PyPI/source installs use the same setup flow after installation: project directories get a local .mcp.json; global setup registers a detected client directly (see below).

Register the server in your MCP client

Setup has two steps:

1. Install the server once — uv tool install / pipx / pip puts the openproject-ce-mcp command on your PATH (source installs build it in .venv), regardless of how many clients or projects you use.

2. Register it per client — each client needs its own config file pointing at that command. Registration only points your client to the installed command; it is not a second install. Using more than one client (say Claude and Codex)? Create one config file per client; they sit side by side.

Which guide do I use? Use VS Code → the GitHub Copilot guide. Use Claude Code → the Claude guide. Use the Claude desktop app → the Claude Desktop guide. Use Cursor or Codex → their own guide. Any other MCP client → the generic note below.

The file, location, and format differ per client — you cannot copy one client's config to another verbatim:

VS Code users: the Copilot guide below is your guide — VS Code runs MCP servers through GitHub Copilot in Agent mode.

openproject-ce-mcp configure can write these files for you. Before collecting your settings it asks two independent questions:

• Configure globally (user-wide)? — adds the server to a detected client's user-wide config, available in every project.

• Configure project-scoped (this directory)? — writes config files into the current directory for every supported client (offered whether or not the client is detected), plus a generic .mcp.json you can copy from.

Choose one or both; choosing neither aborts without writing anything. Only the openproject entry is written; existing entries for other MCP servers are kept and each edited file is backed up first.

To register manually instead, copy the command and env values from the generated .mcp.json into the file and format your client's guide shows — the values are identical across clients.

Follow the guide for your client:

• Claude / Claude Code

• Claude Desktop app

• Codex

• Cursor

• VS Code / GitHub Copilot

Any other MCP client (Windsurf, JetBrains AI Assistant/Junie, Cline, Continue, Warp, Zed, …) uses the same pattern: point command at the binary from the generated .mcp.json and copy the env values. The root key is almost always mcpServers (Zed uses context_servers with "source": "custom"; Continue uses YAML with the same fields).

Each guide shows the project-scoped and/or user-wide config, how to reload the client, and how to verify the server is picked up.

Troubleshooting

Uninstall

First unregister the server. This removes the openproject entry from your clients' user-wide configs and from project-local configs in the current directory (.mcp.json, .codex/config.toml, .vscode/mcp.json, .cursor/mcp.json) — so run it from the project directory to clean that up too. Your other MCP servers and settings are kept and each edited file is backed up first; results are listed grouped by scope:

openproject-ce-mcp configure --uninstall   # or: openproject-ce-mcp-setup --uninstall

Then remove the package itself, matching how you installed it:

uv tool uninstall openproject-ce-mcp   # or: pipx uninstall openproject-ce-mcp
                                       # or: pip uninstall openproject-ce-mcp

If you installed from source, uninstall.sh / uninstall.ps1 also remove the local environment (.venv, caches, the API-source clones) in addition to unregistering the client entries:

• Windows: .\uninstall.ps1 (then remove the install dir if you want: Remove-Item -Recurse -Force $env:USERPROFILE\openproject-ce-mcp)

• macOS / Linux: ~/openproject-ce-mcp/uninstall.sh

Configuration

Your client config (.mcp.json, .codex/config.toml, or .vscode/mcp.json) contains your API token. Treat it like a password. This repo gitignores .mcp.json, but when you place a project-scoped config in your own project, add it to that project's .gitignore so the token is never committed.

Access is grouped into five chains: project, membership, work_package, version, and board. Each chain has a read flag and a write flag. Scoped flags control each chain independently.

Supported entities for OPENPROJECT_HIDE_<ENTITY>_FIELDS: project, membership, role, principal, user, group, project_access, project_admin_context, project_configuration, action, capability, job_status, project_phase_definition, project_phase, view, query_filter, query_column, query_operator, query_sort_by, query_filter_instance_schema, document, news, wiki_page, category, attachment, time_entry_activity, time_entry, work_package, relation, activity, reminder, version, board, current_user, instance_configuration.

Never share your API token in chat messages, screenshots, or log output. If a token has been exposed, revoke it immediately in My account → Access tokens and create a new one.

Tools

Tools are grouped by area: projects, memberships, users, groups, work packages, versions, boards, time entries, wiki, news, documents, notifications, grids, and more.

See the full tool reference for descriptions of every tool.

Errors

Every tool failure carries a stable, machine-readable category as a leading [category] prefix on the error message, so an agent can branch on the failure type instead of parsing free text. The categories are:

Successful write previews are not errors — they return a structured result with ready, requires_confirmation, validation_errors, and a human-readable message.

Integrations

The server communicates over stdio and is compatible with any MCP client. Client-specific setup guides are available in the docs/ folder.

Architecture

Five files, no deep abstractions:

• config.py — environment parsing and safe defaults

• client.py — HTTP access, policy checks, HAL normalization, preview/confirm writes

• models.py — compact dataclasses returned to MCP clients

• tools.py — validated MCP tool handlers

• server.py — FastMCP lifecycle wiring

client.py is intentionally large: all policy-sensitive logic (read gates, write gates, project scoping, field hiding) lives in one place to make it easier to audit.

See docs/architecture.md for request flow details and the safety model.

Development

Set up

git clone https://github.com/jtauschl/openproject-ce-mcp.git
cd openproject-ce-mcp

# option A: uv (recommended)
uv sync --dev

# option B: venv + pip
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Run tests

Unit tests (no network — run against httpx mocks):

# uv
uv run pytest

# venv
.venv/bin/python -m pytest

Integration tests (require a live OpenProject instance):

OPENPROJECT_BASE_URL=https://op.example.com \
OPENPROJECT_API_TOKEN=opapi-... \
OPENPROJECT_TEST_PROJECT=mcp-test \
uv run pytest -m integration -v

OPENPROJECT_TEST_PROJECT is the project identifier used for write tests (default: mcp-test). Integration tests are excluded from the default run (-m 'not integration') and must be opted in explicitly.

For local, throwaway instances across the OpenProject versions where the API changed (16.6 classic + 17.4 displayId + 17.5 semantic/workspaces), see docker/test/ — docker/test/up.sh boots and seeds them and prints the env block to run the integration tests against each. To verify the client's API assumptions against the OpenProject source across releases, see tools/api-check/.

After code changes

The MCP server runs as a subprocess. After any code change, restart your MCP client before updated tools become active.

Releasing

The package is published to PyPI via GitHub Actions using trusted publishing (OIDC — no API token stored). Pushing a vX.Y.Z tag triggers .github/workflows/publish.yml, which runs the test matrix, builds the sdist + wheel, and uploads them. Every push and PR also runs the test matrix plus a build job (uv build + uvx twine check dist/*) so the package always stays buildable.

To cut a release:

1. Bump version in pyproject.toml and update CHANGELOG.md.

2. uv run pytest and uv build locally (CI enforces both).

3. Merge to main, then tag: git tag vX.Y.Z && git push origin vX.Y.Z.

4. The publish.yml workflow builds and uploads to PyPI automatically. Create the GitHub release from the tag for release notes.