convez.ai
MCP Server
OliverRhyme

openproject-mcp

OliverRhyme/openproject-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for OpenProject — projects, work packages, attachments, notifications, and more

Instalação

$npx convez-ai OliverRhyme/openproject-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
11
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

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

VariableRequiredDefaultNotes
OPENPROJECT_BASE_URLyes--e.g. https://community.openproject.org
OPENPROJECT_API_KEYyes--From My account > Access tokens > API
OPENPROJECT_PAGE_SIZEno25Default page size for list endpoints
OPENPROJECT_TIMEOUT_MSno30000HTTP request timeout in milliseconds

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

ToolDescription
op_list_projectsList projects with filter/sort/paginate
op_get_projectGet project by id or identifier slug
op_create_projectCreate a new project
op_update_projectPatch project fields
op_delete_projectDelete a project (destructive, async)
op_count_projectsCount projects matching filters

Work packages

ToolDescription
op_list_work_packagesList work packages, optionally scoped to a project
op_get_work_packageGet a single work package by id
op_create_work_packageCreate a work package (requires subject, projectId, typeId)
op_update_work_packagePatch work package fields (requires lockVersion)
op_delete_work_packageDelete a work package (destructive)
op_list_work_package_activitiesList comments and change history
op_comment_work_packageAdd a comment, optionally attaching and embedding a file inline
op_count_work_packagesCount work packages matching filters

Relations

ToolDescription
op_list_relationsList relations on a work package (blocks, precedes, duplicates, etc.)
op_get_relationGet a single relation by id
op_create_relationCreate a relation between two work packages
op_delete_relationDelete a relation

Attachments

ToolDescription
op_list_attachmentsList attachments on a work package
op_get_attachmentGet attachment metadata; optionally download to a local path
op_upload_attachmentUpload a local file; optionally embed in a comment or WP description
op_delete_attachmentDelete an attachment (destructive)

Users

ToolDescription
op_current_userGet the user tied to the configured API key
op_list_usersList users with filter/sort/paginate
op_get_userGet a user by id

Notifications

ToolDescription
op_list_notificationsList in-app notifications for the current user
op_get_notificationGet a single notification by id
op_mark_notification_readMark one notification as read
op_mark_all_notifications_readMark all notifications as read

Watchers

ToolDescription
op_list_watchersList users watching a work package
op_add_watcherAdd a user as a watcher
op_remove_watcherRemove a user from watching

Boards

ToolDescription
op_list_boardsList Kanban-style boards for a project
op_get_boardGet board details including column config

Reference data

ToolDescription
op_list_typesList work package types (Task, Bug, Feature, etc.)
op_list_statusesList all work package statuses
op_list_prioritiesList all priorities
op_list_versionsList versions/milestones, optionally per project
op_api_passthroughRaw GET against any /api/v3 path (escape hatch)

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:

OperatorMeaning
=Equals
!Not equals
~Contains (substring)
oOpen statuses
cClosed statuses
>=Greater or equal
<=Less or equal
*Any (not empty)
!*None (empty)

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
CommandPurpose
npm installInstall dependencies
npm run buildCompile TypeScript to dist/
npm startRun the compiled server (requires build)
npm run devWatch-mode server via tsx (no build)
npm testRun test suite
npm run test:watchRun tests in watch mode
npm run typecheckType-check without emitting

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

Ver o original no GitHub

Relacionados