3.3 KiB

Raw Blame History

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

Clone and install:

git clone https://gitea.kollect.biz/KollectRnD/MCP-OpenProject.git
cd MCP-OpenProject
pnpm install

Configure environment:

cp .env.example .env

Edit .env with your OpenProject URL and API key:

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

Build:
```
pnpm 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:

pnpm dev

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

3.3 KiB Raw Blame History