OpenProject MCP Server

An MCP server that gives AI agents — Claude, GitHub Copilot, Cursor, Codex, Gemini, or any other MCP client — structured access to OpenProject: projects, work packages, sprints and versions, relations, time tracking, attachments, and progress reports.

Ask your agent things like:

• "What's assigned to me and overdue in the Website project?"

• "Break the checkout redesign into phases and tasks, with dependencies."

• "Move #1234 to In progress and log 2 hours against it."

• "Write a status report for Sprint 7."

Features

Work management

• Find work packages by assignee, status, type, version, dates, or text — open work by default, everything on request — and read one in full, with custom fields and history.

• Create single work packages or whole hierarchies in one call; update dates, priority, assignee, effort, progress, and custom fields; move status through the workflow.

• Maintain a living status section inside a description, post notes, and bulk-edit many work packages at once.

Planning and tracking

• Sprints and releases as versions; dependencies (precedes, blocks, relates, …) between work packages; project health status.

• Time entries: log, review, correct, and delete.

• Progress reports for a project or sprint: completion, overdue and blocked work, effort against estimates.

• Read project documents and work package attachments; upload text attachments.

Safety

• Destructive and bulk tools are dry runs until called with dry_run=False, confirm=True.

• Edits use OpenProject's optimistic locking and are retried against fresh state, so a concurrent human edit is never overwritten.

• Names (priority="High", version="Sprint 4") are resolved and checked; an unknown name fails with the list of valid ones instead of guessing.

• An optional allowlist confines every tool to chosen projects — a guard against agent mistakes and instructions injected through ticket content.

Deployment

• Runs locally over stdio, or as a shared HTTP service where each person authenticates with their own OpenProject token and acts as themselves.

• Switch off whole tool categories you do not use, so the model has fewer tools to choose between.

• Built-in diagnostics, structured logs on stderr, optional usage telemetry and a read-only usage dashboard.

• Two agent skills for operating the tools and planning work, installable as a Claude Code plugin.

Related MCP server: OpenProject MCP Server

Contents

• Features

• Setup guide

  1. Get an OpenProject instance

  2. Create an API token

  3. Install the server

  4. Connect your AI client

  5. Verify

• Running as a shared HTTP service

• Configuration

• Tools

• Agent skills

• Development

• Documentation

Setup guide

1. Get an OpenProject instance

Any OpenProject 16.3 or later works — self-hosted or OpenProject Cloud. If you already have one, skip to step 2.

To try it locally, the official all-in-one container is the quickest route (full instructions):

docker run -d --name openproject -p 8080:80 \
  -e SECRET_KEY_BASE="$(openssl rand -hex 64)" \
  -e OPENPROJECT_HOST__NAME=localhost:8080 \
  -e OPENPROJECT_HTTPS=false \
  -e OPENPROJECT_DEFAULT__LANGUAGE=en \
  -v openproject_pgdata:/var/openproject/pgdata \
  -v openproject_assets:/var/openproject/assets \
  openproject/openproject:17

First start takes a few minutes. Then open http://localhost:8080, sign in as admin / admin, and set a new password when prompted. Create a project to play with.

This is a local, plain-HTTP setup for evaluation. For anything shared, follow OpenProject's production guides (HTTPS, a real SECRET_KEY_BASE, backups).

2. Create an API token

The server acts as the user whose token it holds, with exactly that user's permissions — so consider a dedicated user that is a member of only the projects the agent should touch.

1. In OpenProject, open your avatar → Account settings → Access tokens.

2. Under API, click + API token, give it a name, and Create.

3. Copy the token now — it is shown only once.

If the API section is missing, an administrator needs to enable it under Administration → API and webhooks. Check the token works:

curl -s -u apikey:YOUR_TOKEN http://localhost:8080/api/v3/users/me | head -c 200

A JSON body with your name means you are ready. 401 means the token is wrong.

3. Install the server

You need Python 3.11+ and uv.

git clone https://github.com/zilligm/openproject-mcp.git
cd openproject-mcp
uv sync
cp example.env .env

Edit .env and set the two required values:

OPENPROJECT_URL=http://localhost:8080        # your instance's base URL, no /api/v3
OPENPROJECT_TOKEN=your_api_token_here

.env is gitignored. Never commit it — the token carries every permission its user has.

4. Connect your AI client

Most clients launch the server themselves over stdio: no port is opened, and the credentials come from the .env in the repository. In every snippet below, replace /path/to/openproject-mcp with the absolute path of your clone.

Claude Code

claude mcp add openproject -- uv run --directory /path/to/openproject-mcp server.py --transport stdio

Add --scope user to make it available in every project, not just the current one.

Claude Desktop

Open Settings → Developer → Edit Config and add to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "openproject": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/openproject-mcp", "server.py", "--transport", "stdio"]
    }
  }
}

If Claude Desktop cannot find uv, use its absolute path (which uv) as command.

Other clients

The same command works in any MCP client that can launch a local server. docs/clients.md has ready-to-paste configurations for:

It also covers connecting to a server over HTTP, the Claude Code plugin, and why cloud-hosted connectors (claude.ai custom connectors, ChatGPT) cannot reach a server on your own network.

5. Verify

Ask your agent:

Call get_operational_diagnostics.

It is read-only, and reports whether OpenProject is reachable, its version, and which user the token acts as. Then try "List my OpenProject projects."

Something wrong? Without any AI client, the MCP Inspector lets you call tools by hand:

npx @modelcontextprotocol/inspector uv run --directory /path/to/openproject-mcp server.py --transport stdio

Common causes are in Troubleshooting.

Running as a shared HTTP service

For a team, run one long-lived server and let each person connect with their own OpenProject token. The server holds no secret of its own: it verifies each caller's bearer token with OpenProject and acts as that person — their permissions, their name on every edit.

A multi-arch image (x86-64 and arm64) is published to GitHub Container Registry:

cp example.env .env        # set OPENPROJECT_URL; keep MCP_TRANSPORT=streamable-http
docker compose up -d       # or: docker compose up -d --build, to build this checkout

The endpoint is http://<host>:8001/mcp. Clients send:

Authorization: Bearer <their OpenProject API token>

For Claude Code:

claude mcp add --transport http openproject http://your-host:8001/mcp \
  --header "Authorization: Bearer YOUR_OPENPROJECT_API_TOKEN"

Without Docker: uv run server.py --transport streamable-http --port 8000.

Expose the port only on networks you trust, or put it behind an HTTPS reverse proxy. If OpenProject runs on the same host as the container, localhost inside the container is the container itself — use the host's address in OPENPROJECT_URL.

docs/operations.md covers deployment end to end: verifying it, updating it, private CAs, and the optional usage dashboard.

Configuration

All settings are environment variables, read from .env. The ones you are likely to touch:

Every variable is described in example.env and in docs/operations.md.

Tools

36 tools covering projects, work packages (dates, priority, versions, effort, progress, custom fields), versions (sprints and releases), notes and history, relations, members, time tracking, progress reporting, documents, attachments, and diagnostics. The full reference, generated from the code, is in docs/tools.md.

Tool selection guide

The server also exposes two MCP prompts, openproject_usage_guide and openproject_safe_mode_guide, for clients that support them.

Agent skills

skills/ holds two agent skills that teach a model to use these tools well: openproject for day-to-day operation, and project-planning for structuring work into phases, milestones and tasks. In Claude Code, the repository installs as a plugin that brings the skills along:

claude plugin marketplace add zilligm/openproject-mcp
claude plugin install openproject-mcp@openproject-tools

The plugin connects over HTTP, so it expects a running server. See skills/README.md for installing the skills on their own, alongside a stdio setup.

Development

uv sync
uv run pytest -m "not integration"     # unit tests, no live instance needed
uv run ruff check .                    # lint

docs/development.md covers conventions, the live integration suite, and adding a tool. Read docs/architecture.md first.

Documentation

Disclaimer

This is an independent, community project. It is not affiliated with, endorsed by, or supported by OpenProject GmbH; "OpenProject" is a trademark of its respective owner and is used here only to describe what this software connects to.

The server lets an AI agent read and change real data in your OpenProject instance, with every permission of the API token it is given. Language models can misread requests and make mistakes, and the safeguards described above reduce that risk but do not remove it. You are responsible for how you deploy and use this software and for any actions taken through it. Use a token with only the permissions you need, try it against a non-critical project first, and keep backups of data you cannot afford to lose.

The software is provided "as is", without warranty of any kind; see the license for the full terms.

License

MIT