openproject-mcp

An MCP server that exposes the OpenProject REST API (v3) as tools usable by Claude Desktop, Claude Code, Cursor, and any other MCP client.

Install

Before you start: you need an OpenProject API token. Get one from My account > Access tokens > API in your OpenProject instance.

Pick your MCP client and run one command:

Claude Code

claude mcp add openproject \
  --env OPENPROJECT_BASE_URL=https://your-instance.openproject.com \
  --env OPENPROJECT_API_KEY=your-token \
  -- npx -y github:OliverRhyme/openproject-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openproject": {
      "command": "npx",
      "args": ["-y", "github:OliverRhyme/openproject-mcp"],
      "env": {
        "OPENPROJECT_BASE_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-token"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "openproject": {
      "command": "npx",
      "args": ["-y", "github:OliverRhyme/openproject-mcp"],
      "env": {
        "OPENPROJECT_BASE_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-token"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "openproject": {
      "command": "npx",
      "args": ["-y", "github:OliverRhyme/openproject-mcp"],
      "env": {
        "OPENPROJECT_BASE_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-token"
      }
    }
  }
}

Any other MCP client (generic stdio)

Run this as the server process:

OPENPROJECT_BASE_URL=https://your-instance.openproject.com \
OPENPROJECT_API_KEY=your-token \
npx -y github:OliverRhyme/openproject-mcp

The server speaks JSON-RPC over stdio. No build step needed — npx fetches, installs, and runs it directly from GitHub.

Configuration

Features

• Projects -- list, get, create, update, delete, count

• Work packages -- list, get, create, update (with lockVersion), delete, activity/comment thread, inline file attachments on comments, count

• Relations -- list, get, create, delete (blocks, precedes, relates, duplicates, etc.)

• Attachments -- list, get (with download), upload (with auto-embed in description or comment), delete

• Users -- current user, list, get

• Notifications -- list, get, mark read, mark all read

• Watchers -- list, add, remove watchers on work packages

• Boards -- list and get Kanban-style boards

• Reference data -- work package types, statuses, priorities, versions

• Raw passthrough -- call any GET endpoint under /api/v3 directly

• Filter, sort, group, and paginate via OpenProject's native query syntax

• Output optimization -- field selection, description truncation, hasMore pagination flag, lightweight count tools

Tools reference

All tools are prefixed op_ to avoid collisions with other MCP servers.

Projects

Work packages

Relations

Attachments

Users

Notifications

Watchers

Boards

Reference data

Usage patterns

Filter syntax

List endpoints accept OpenProject's structured filter format:

{
  "projectIdOrIdentifier": "web",
  "filters": [
    { "field": "status_id", "operator": "o", "values": null },
    { "field": "assignee", "operator": "=", "values": ["42"] },
    { "field": "type", "operator": "=", "values": ["1"] }
  ],
  "sortBy": [["updatedAt", "desc"]],
  "pageSize": 50
}

Common operators:

Filter values are always strings, even for numeric ids: "values": ["42"], not [42].

Output optimization

List tools return summarized output by default. Several options keep responses small:

fields -- Return only specific fields per element:

// op_list_work_packages
{ "fields": ["id", "subject", "status"] }
// -> elements contain only { id, subject, status }

raw -- Get the full HAL+JSON document from OpenProject:

// op_get_work_package
{ "id": 17, "raw": true }

Count tools -- When you only need a number, use op_count_work_packages or op_count_projects instead of listing:

// op_count_work_packages
{ "projectIdOrIdentifier": "web", "filters": [{ "field": "status_id", "operator": "o", "values": null }] }
// -> { "total": 42 }

Pagination -- All list responses include hasMore: true|false so you know if there are more pages. Max pageSize is 100; default is 25.

Truncation -- Project descriptions are truncated to 200 chars in list mode. Activity comments are truncated to 500 chars by default; pass full: true to op_list_work_package_activities for complete text.

Updating work packages (lockVersion)

OpenProject uses optimistic locking. You must pass the current lockVersion when updating a work package -- fetch it first with op_get_work_package:

// 1. Get current state
// op_get_work_package { "id": 17 }
// -> { ..., "lockVersion": 4 }

// 2. Update with lockVersion
// op_update_work_package
{
  "id": 17,
  "lockVersion": 4,
  "statusId": 7,
  "percentageDone": 50
}

Uploading and embedding attachments

Upload a file and auto-embed it as an image in a comment:

// op_upload_attachment
{
  "workPackageId": 17,
  "filePath": "/path/to/screenshot.png",
  "embedIn": "comment",
  "embedText": "Here's the updated design:"
}

Or attach a file when commenting:

// op_comment_work_package
{
  "id": 17,
  "comment": "Fixed in latest build, see attached screenshot.",
  "attachFilePath": "/path/to/screenshot.png"
}

Creating relations

Link work packages with dependency or reference relations:

// op_create_relation
{
  "fromId": 17,
  "toId": 23,
  "type": "blocks"
}

Relation types: relates, duplicates, blocks, precedes, follows, includes, partOf, requires.

Local development

git clone https://github.com/OliverRhyme/openproject-mcp.git
cd openproject-mcp
npm install
npm run dev

Smoke test

Verify the server boots and lists tools without a real OpenProject instance:

OPENPROJECT_BASE_URL=https://example.openproject.com OPENPROJECT_API_KEY=fake \
  node dist/index.js <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

License

MIT