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

Tool	Description
op_list_projects	List all projects
op_get_project	Get project details
op_create_project	Create a new project
op_update_project	Update project
op_delete_project	Delete a project
op_list_project_members	List project members
op_add_project_member	Add member to project
op_remove_project_member	Remove member from project
op_list_project_versions	List project versions
op_create_version	Create a version
op_list_work_packages	List work packages
op_get_work_package	Get work package details
op_create_work_package	Create a work package
op_update_work_package	Update work package
op_delete_work_package	Delete work package
op_list_work_package_activities	List activities
op_add_work_package_comment	Add comment
op_list_work_package_relations	List relations
op_create_work_package_relation	Create relation
op_delete_work_package_relation	Delete relation
op_get_project_work_packages	Get all WPs in project
op_list_statuses	List all statuses
op_list_types	List all types
op_get_project_types	List types in project
op_list_priorities	List all priorities
op_list_users	List all users
op_get_user	Get user details
op_get_current_user	Get current user
op_list_project_assignees	List assignable users
op_list_roles	List all roles
op_list_groups	List all groups
op_search	Search work packages

Architecture

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

License

MIT