OpenProject MCP Server

A high-quality Model Context Protocol (MCP) server for connecting Claude to your OpenProject instance. It allows Claude to query, search, and manage projects, work packages, users, and time entries directly from conversations.

🚀 Features

✅ Project Access - List, filter, and get project details
✅ Work Package Management - View tasks, bugs, features with advanced filtering
✅ Full-Text Search - Search work packages by content
✅ Activity History - View changes and comments on work packages
✅ User Management - List and get user information
✅ Time Entries - Query logged time by project, user, period
✅ Smart Pagination - Support for large datasets
✅ Robust Error Handling - Clear and actionable messages
✅ Full Typing - TypeScript for maximum type safety

Related MCP server: OpenProject MCP Server

📋 Prerequisites

• Node.js 18+ or Bun 1.0+

• An OpenProject 13+ instance with API access

• An OpenProject API Token (generatable in Settings)

🔧 Installation

1. Clone or download the server

cd openproject-mcp-server

2. Install dependencies

npm install
# o con bun
bun install

3. Configure environment variables

Copy .env.example to .env and fill in the values:

cp .env.example .env

Edit .env:

OPENPROJECT_URL=https://openproject.empresa.com
OPENPROJECT_API_TOKEN=tu-token-api-aqui
OPENPROJECT_PAGE_SIZE=50

How to generate an API Token in OpenProject:

1. In OpenProject, go to Administration → API & Webhooks → Personal Access Tokens

2. Click "+ New Personal Access Token"

3. Give it a descriptive name (e.g. "Claude MCP")

4. Check the required permissions:

   • ✅ view_work_packages

   • ✅ view_projects

   • ✅ view_users

   • ✅ view_time_entries

   • ✅ edit_work_packages (if you want to create/edit)

5. Copy the generated token to .env

4. Build the server

npm run build

🎯 Usage

Option A: In Claude Code

1. Open Claude Code

2. Go to Settings → MCP Servers

3. Click + Add Local Server

4. Configure:

   • Name: openproject

   • Command: node

   • Arguments: ["path/to/openproject-mcp-server/dist/index.js"]

   • Environment Variables: The values from .env

5. Save and reconnect to Claude

Option B: Run locally for testing

npm run dev

Then in another terminal, use the MCP Inspector:

npm run inspect

This opens a web interface where you can test each tool.

Option C: On Claude.ai

1. Open claude.ai/code

2. Go to Settings → MCP Servers

3. Add a remote server if you deployed this server on an accessible host

4. Configure access credentials

🛠️ Available Tools

📦 Projects

list_projects

Lists all projects with optional filtering.

Parameters:

• offset (number, optional): For pagination

• name_filter (string, optional): Filter by name

• status (enum: "active" | "archived", optional): Filter by status

Example:

Claude: List all active projects
→ OpenProject: Muestra proyectos activos

get_project

Gets full details of a project.

Parameters:

• project_id (string | number): Project ID or identifier

📋 Work Packages (Tasks)

list_work_packages

Lists work packages with advanced filtering.

Parameters:

• project_id (string | number, optional): Filter by project

• status (string, optional): Status (e.g. "Open", "In Progress")

• priority (string, optional): Priority

• assignee_id (number, optional): Assigned to user

• search (string, optional): Text search

• offset (number, optional): Pagination

get_work_package

Gets full details of a work package.

Parameters:

• work_package_id (number): Work package ID

get_work_package_activities

Gets the history of changes and comments.

Parameters:

• work_package_id (number): Work package ID

search_work_packages

Full-text search in work packages.

Parameters:

• query (string, required): Search term

• project_id (string | number, optional): Limit to project

• status (string, optional): Filter by status

• priority (string, optional): Filter by priority

👤 Users

list_users

Lists all users in OpenProject.

Parameters:

• offset (number, optional): Pagination

get_user

Gets details of a specific user.

Parameters:

• user_id (number): User ID

⏱️ Time Entries

list_time_entries

Lists time entries with filtering by period, user, project.

Parameters:

• work_package_id (number, optional): Filter by work package

• user_id (number, optional): Filter by user

• project_id (string | number, optional): Filter by project

• from_date (string, optional): Start date (YYYY-MM-DD)

• to_date (string, optional): End date (YYYY-MM-DD)

• offset (number, optional): Pagination

get_time_entry

Gets details of a time entry.

Parameters:

• time_entry_id (number): Time entry ID

✍️ Writing (Create Epics and User Stories)

list_project_types

Lists the work package types available in a project (Epic, User Story, Task, Bug...) with their ID. Use this first — type IDs vary between OpenProject instances.

Parameters:

• project_id (string | number): Project ID or identifier

create_work_package

Creates a work package (Epic, User Story, Task, etc.). Use parent_id to hang a User Story under its Epic.

Parameters:

• project_id (string | number)

• subject (string)

• description (string, optional, Markdown)

• type_id (number, optional): Type ID, obtained with list_project_types

• parent_id (number, optional): Parent Epic ID

• priority_id, assignee_id, start_date, due_date (optional)

create_work_packages_bulk

Creates multiple work packages in a single call (ideal for uploading all User Stories extracted from a Word document). Each item can have its own parent_id, so stories from different epics can be created in the same call. Returns a per-item report (success/error), it does not abort the whole batch if one fails.

Parameters:

• project_id (string | number)

• items (array, max 100): each with the same fields as create_work_package (except project_id)

📋 Flow: Upload Epics and User Stories from Word

Typical team use case: they have user stories written in .docx and need to load them into OpenProject respecting the Epic → Story relationship.

1. Generate your personal API Token (each developer uses their own, see above) and configure your local .env.

2. Open the conversation with Claude and attach or reference the .docx file with the epics/stories (Claude can read it directly).

3. Ask Claude: "Read this Word document, identify the epics and their user stories, and upload them to project X in OpenProject".

4. Claude will typically do, without you having to orchestrate it manually:

   • list_project_types on the project to find out the type_id for Epic and User Story.

   • create_work_package for each Epic (few, done one by one to have their IDs).

   • create_work_packages_bulk for the User Stories, using the parent_id of the corresponding Epic for each one.

5. Review the final report (what was created, what failed) and fix it in OpenProject if needed.

Note: the token needs the edit_work_packages permission (see token generation section) to be able to create, not just read.

📊 Use Cases

1. Project Analysis

Claude: "Análiza todos los proyectos activos y resume cuáles tienen más work packages abiertos"
→ El servidor lista proyectos, luego itera para contar paquetes abiertos

2. Task Search

Claude: "Busca todas las tareas sobre 'API' en estado 'In Progress' del proyecto BACKEND"
→ search_work_packages con query="API", status="In Progress", project_id="BACKEND"

3. Time Report

Claude: "¿Cuántas horas registró Juan en la última semana?"
→ list_time_entries con user_id=juan, from_date=última_semana

4. Project Status

Claude: "Dame un resumen del proyecto FRONTEND: qué se completó, qué está en progreso y qué sigue"
→ get_project + list_work_packages con diferentes status

5. Change Audit

Claude: "¿Quién cambió el estado del work package #123 y cuándo?"
→ get_work_package_activities para ver el historial

🏗️ Architecture

src/
├── index.ts                 # Entry point del servidor MCP
├── client/
│   └── openproject.ts       # Cliente HTTP para OpenProject API
├── tools.ts                 # Registro e implementación de herramientas
├── schemas/
│   └── index.ts             # Validación Zod de inputs
└── utils/
    └── formatters.ts        # Formatos de salida Markdown

🔐 Security

• ✅ Bearer Token authentication (secure, no plain-text credentials required)

• ✅ Input validation with Zod (prevents injections)

• ✅ Granular error handling (does not expose sensitive data)

• ✅ TypeScript strict mode (prevents type errors)

• ⚠️ The token is stored in .env - DO NOT commit this file to git

🚨 Troubleshooting

"Authentication failed"

• Verify that the token in .env is valid

• Regenerate a new token in OpenProject

"Connection error"

• Verify that OPENPROJECT_URL is accessible from your machine

• If you use a proxy/VPN, configure proxy environment variables

"No projects found"

• Verify that your user has permission to view projects

• Verify that projects exist in your instance

Server does not start

npm run build
npm run dev

Check the error output in the terminal.

📈 Upcoming Improvements

• Support for creating/editing work packages from Claude

• Support for comments on work packages

• Integration with Gantt charts

• Webhooks for real-time notifications

• Data caching for better performance

• Comprehensive evaluations (SEP)

📦 Distributing to your development team

Each developer needs their own copy + their own API Token (never share a token between multiple people — actions are audited per user in OpenProject).

Recommended option: shared Git repo

1. Upload this folder to a private repository (GitHub org or the linux.ie Gitea/GitLab). Don't forget that .env is already in .gitignore — it never gets uploaded.

2. Each developer:

   git clone <url-del-repo>
   cd openproject-mcp-server
   npm install
   npm run build
   cp .env.example .env

3. Each one generates their own token (Administration → API & Webhooks → Personal Access Tokens, with the edit_work_packages permission if they are going to create stories) and pastes it into their .env.

4. Each one adds it in Claude Code (Settings → MCP Servers → Add Local Server) pointing to their local dist/index.js.

Alternative without Git: compressed folder

If you don't want to set up the repo yet, you can share a .zip of the folder (excluding node_modules, dist, and .env) and have each dev run npm install && npm run build locally. It's the same mechanics, only the distribution medium changes — no CI/CD required because there is no central server to deploy: the MCP runs over stdio on each developer's machine.

If you later run it as a shared remote server

If instead of each dev running it locally you prefer a single server (on linux.ie, for example) that everyone consumes, then CI/CD does apply (build + deploy on each push) and the transport would need to be migrated from stdio to HTTP. That's a major architecture jump — let me know if that's the path you want and we'll plan it separately.

🤝 Contributing

This is an open-source MCP server. To improve it:

1. Fork the repository

2. Create a branch for your feature (git checkout -b feature/my-feature)

3. Commit your changes (git commit -am 'Add my-feature')

4. Push to the branch (git push origin feature/my-feature)

5. Open a Pull Request

📄 License

MIT - Feel free to use, modify, and distribute

💬 Support

To report bugs, ask questions, or make suggestions:

• Open an issue in the repository

• Check the MCP documentation

• Review the OpenProject API documentation

Created with ❤️ for Integral de Empaques S.A.S.