OpenProject MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to OpenProject via the v3 REST API.

Features

• 18 MCP tools covering projects, work packages, relations, users, time tracking, versions, and activities
• Stdio transport — works with Claude Code, Zed, Claude Desktop, and any MCP-compatible client
• HAL+JSON responses formatted into readable text summaries
• Optimistic concurrency control for work package updates

Prerequisites

• Node.js 18+
• pnpm
• An OpenProject instance with an API key

Setup

1. Clone and bootstrap:

   git clone https://gitea.kollect.biz/KollectRnD/MCP-OpenProject.git
   cd MCP-OpenProject
   just bootstrap    # installs uv, just, commitizen, pre-commit, git hooks
   just install      # pnpm install
   

2. Configure environment:

   cp .env.example .env
   cp .mcp.json.example .mcp.json
   

   Edit .env with your OpenProject URL and API key:

   OPENPROJECT_URL=https://your-instance.openproject.com
   OPENPROJECT_API_KEY=your-api-key-here
   

   Edit .mcp.json and replace <YOUR_API_KEY_HERE> with your key.

   Note: .env and .mcp.json are gitignored — secrets stay local.

3. Build:

   just build
   

Usage

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "openproject": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "openproject": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-OpenProject/dist/index.js"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Development

Run directly without building:

just dev

Just Commands

just install      # Install dependencies
just build        # Compile TypeScript
just dev          # Run with tsx (no build)
just start        # Run compiled server
just bootstrap    # Full setup (first time)
just setup        # Install commitizen + pre-commit
just update       # Update pre-commit hooks
just changelog    # Generate CHANGELOG.md
just bump         # Bump version (SemVer)

Available Tools

Tool	Description
list_projects	List all accessible projects
get_project	Get project details by ID or identifier
list_work_packages	List work packages with filtering
get_work_package	Get work package details
create_work_package	Create a new work package
update_work_package	Update an existing work package
add_work_package_comment	Add a comment to a work package
list_relations	List relations for a work package
create_relation	Create a relation between work packages
delete_relation	Delete a relation
list_statuses	List available statuses
list_types	List available types (Task, Bug, Feature, etc.)
list_priorities	List available priorities
get_me	Get authenticated user profile
list_users	List all users
list_time_entries	List time entries
log_time	Log time on a work package
list_versions	List project versions/milestones
list_work_package_activities	List work package activity history

Project Structure

src/
  index.ts      — Entry point, server bootstrap, tool registration
  client.ts     — OpenProject API v3 HTTP client
  tools.ts      — MCP tool definitions with Zod schemas
  handlers.ts   — Tool handlers (API calls + response formatting)

License

Private — Kollect Systems