OpenProject MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with OpenProject's APIv3 for autonomous project management.

Overview

This MCP server provides a comprehensive set of tools that allow an AI agent to:

• List, create, update, and delete projects
• Manage work packages (tasks, bugs, features, etc.)
• Handle project members and versions
• Query statuses, types, priorities, users, and roles
• Search across work packages

Features

Projects

• List all projects with pagination and filtering
• Get detailed project information
• Create new projects
• Update project details (name, description, status)
• Delete projects
• Manage project members (add/remove)
• Manage project versions

Work Packages

• List work packages with advanced filtering
• Get detailed work package information
• Create new work packages
• Update work packages (status, priority, assignee, dates, etc.)
• Delete work packages
• View activity history and comments
• Add comments to work packages
• Manage relations between work packages

Reference Data

• List all available statuses
• List all work package types
• List all priorities
• List all users
• List users available for assignment in a project
• List all roles
• List all groups

Search

• Full-text search across work packages

Prerequisites

• Node.js 18+
• An OpenProject instance with API access

Installation

# Clone or download this repository
cd openproject-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuration

Set the following environment variables:

export OPENPROJECT_BASE_URL="https://your-openproject-instance.com"
export OPENPROJECT_API_KEY="your-api-key"

To get an API key:

1. Log into OpenProject
2. Go to My Account → API Access Keys
3. Generate a new API key

Running

# Set environment variables first
export OPENPROJECT_BASE_URL="https://your-openproject-instance.com"
export OPENPROJECT_API_KEY="your-api-key"

# Run the server
node dist/index.js

Claude Desktop Integration

Add to your claude.json:

{
  "mcpServers": {
    "openproject": {
      "command": "node",
      "args": ["/path/to/openproject-mcp/dist/index.js"],
      "env": {
        "OPENPROJECT_BASE_URL": "https://your-openproject-instance.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}

Usage Example

Here's how an agent might use the tools:

1. List projects to see what's available
2. Get project types to understand what work package types exist
3. Get statuses to know what transitions are possible
4. List users to find assignable team members
5. Create a work package with subject, type, priority
6. Update the work package as work progresses (change status, update assignee)
7. Add comments to document progress
8. Search to find related work packages

Tool Reference

Architecture

• client.ts: OpenProject API client using axios with Basic Auth
• index.ts: MCP server implementation with all tool handlers

License

MIT