OpenProject MCP Server

Высококачественный сервер Model Context Protocol (MCP) для подключения Claude к вашему экземпляру OpenProject. Позволяет Claude запрашивать, искать и управлять проектами, рабочими пакетами (work packages), пользователями и записями времени прямо из диалога.

🚀 Возможности

✅ Доступ к проектам — просмотр, фильтрация и получение деталей проектов
✅ Управление рабочими пакетами — просмотр задач, багов, функций с расширенной фильтрацией
✅ Полнотекстовый поиск — поиск рабочих пакетов по содержимому
✅ История активности — просмотр изменений и комментариев в рабочих пакетах
✅ Управление пользователями — просмотр списка и получение информации о пользователях
✅ Записи времени — запрос учтённого времени по проекту, пользователю, периоду
✅ Умная пагинация — поддержка больших наборов данных
✅ Надёжная обработка ошибок — понятные сообщения и ActionAbles
✅ Полная типизация — TypeScript для максимальной безопасности типов

Related MCP server: OpenProject MCP Server

📋 Предварительные требования

• Node.js 18+ или Bun 1.0+

• Экземпляр OpenProject 13+ с доступом к API

• API-токен OpenProject (создаётся в настройках)

🔧 Установка

1. Клонировать или скачать сервер

cd openproject-mcp-server

2. Установить зависимости

npm install
# o con bun
bun install

3. Настроить переменные окружения

Скопируйте .env.example в .env и заполните значения:

cp .env.example .env

Отредактируйте .env:

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

Как создать API-токен в OpenProject:

1. В OpenProject перейдите в Administration → API & Webhooks → Personal Access Tokens

2. Нажмите "+ New Personal Access Token"

3. Присвойте описательное имя (например, "Claude MCP")

4. Отметьте необходимые разрешения:

   • ✅ view_work_packages

   • ✅ view_projects

   • ✅ view_users

   • ✅ view_time_entries

   • ✅ edit_work_packages (если хотите создавать/редактировать)

5. Скопируйте сгенерированный токен в .env

4. Скомпилировать сервер

npm run build

🎯 Использование

Вариант A: В Claude Code

1. Откройте Claude Code

2. Перейдите в Settings → MCP Servers

3. Нажмите + Add Local Server

4. Настройте:

   • Name: openproject

   • Command: node

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

   • Environment Variables: значения из .env

5. Сохраните и переподключитесь к Claude

Вариант B: Локальный запуск для тестирования

npm run dev

Затем в другом терминале используйте MCP Inspector:

npm run inspect

Откроется веб-интерфейс, где можно протестировать каждый инструмент.

Вариант C: В Claude.ai

1. Откройте claude.ai/code

2. Перейдите в Settings → MCP Servers

3. Добавьте удалённый сервер, если вы развернули этот сервер на доступном хосте

4. Настройте учётные данные для доступа

🛠️ Доступные инструменты

📦 Проекты

list_projects

Выводит список всех проектов с необязательной фильтрацией.

Параметры:

• offset (number, необязательный): для пагинации

• name_filter (string, необязательный): фильтр по названию

• status (enum: "active" | "archived", необязательный): фильтр по статусу

Пример:

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

get_project

Получает полные сведения о проекте.

Параметры:

• project_id (string | number): ID или идентификатор проекта

📋 Рабочие пакеты (Задачи)

list_work_packages

Выводит список рабочих пакетов с расширенной фильтрацией.

Параметры:

• project_id (string | number, необязательный): фильтр по проекту

• status (string, необязательный): статус (например, "Open", "In Progress")

• priority (string, необязательный): приоритет

• assignee_id (number, необязательный): назначенный пользователь

• search (string, необязательный): текстовый поиск

• offset (number, необязательный): пагинация

get_work_package

Получает полные сведения о рабочем пакете.

Параметры:

• work_package_id (number): ID рабочего пакета

get_work_package_activities

Получает историю изменений и комментариев.

Параметры:

• work_package_id (number): ID рабочего пакета

search_work_packages

Полнотекстовый поиск по рабочим пакетам.

Параметры:

• query (string, обязательный): поисковый запрос

• project_id (string | number, необязательный): ограничение по проекту

• status (string, необязательный): фильтр по статусу

• priority (string, необязательный): фильтр по приоритету

👤 Пользователи

list_users

Выводит список всех пользователей в OpenProject.

Параметры:

• offset (number, необязательный): пагинация

get_user

Получает сведения о конкретном пользователе.

Параметры:

• user_id (number): ID пользователя

⏱️ Записи времени

list_time_entries

Выводит список записей времени с фильтрацией по периоду, пользователю, проекту.

Параметры:

• work_package_id (number, необязательный): фильтр по рабочему пакету

• user_id (number, необязательный): фильтр по пользователю

• project_id (string | number, необязательный): фильтр по проекту

• from_date (string, необязательный): начальная дата (YYYY-MM-DD)

• to_date (string, необязательный): конечная дата (YYYY-MM-DD)

• offset (number, необязательный): пагинация

get_time_entry

Получает сведения о записи времени.

Параметры:

• time_entry_id (number): ID записи времени

✍️ Запись (создание эпиков и пользовательских историй)

list_project_types

Выводит список типов рабочих пакетов, доступных в проекте (Epic, User Story, Task, Bug...), с их ID. Используйте его первым — ID типов различаются между экземплярами OpenProject.

Параметры:

• project_id (string | number): ID или идентификатор проекта

create_work_package

Создаёт рабочий пакет (эпик, пользовательскую историю, задачу и т. д.). Используйте parent_id, чтобы прикрепить пользовательскую историю к её эпику.

Параметры:

• project_id (string | number)

• subject (string)

• description (string, необязательный, Markdown)

• type_id (number, необязательный): ID типа, полученный с помощью list_project_types

• parent_id (number, необязательный): ID родительского эпика

• priority_id, assignee_id, start_date, due_date (необязательные)

create_work_packages_bulk

Создаёт несколько рабочих пакетов одним вызовом (идеально для загрузки всех пользовательских историй, извлечённых из Word). Каждый элемент может иметь собственный parent_id, поэтому истории из разных эпиков можно создавать в одном вызове. Возвращает отчёт по каждому элементу (успех/ошибка) и не прерывает весь пакет, если один элемент завершился ошибкой.

Параметры:

• project_id (string | number)

• items (array, макс. 100): каждый элемент с теми же полями, что и create_work_package (кроме project_id)

📋 Процесс: загрузка эпиков и пользовательских историй из Word

Типичный сценарий команды: у них есть пользовательские истории, написанные в .docx, и их нужно загрузить в OpenProject с сохранением связи Эпик → История.

1. Создайте свой личный API-токен (каждый разработчик использует свой, см. выше) и настройте локальный .env.

2. Откройте диалог с Claude и прикрепите или укажите файл .docx с эпиками/историями (Claude может прочитать его напрямую).

3. Попросите Claude: "Прочитай этот Word, определи эпики и их пользовательские истории и загрузи их в проект X в OpenProject".

4. Claude обычно сделает следующее без ручной оркестрации:

   • list_project_types по проекту, чтобы узнать type_id для Epic и User Story.

   • create_work_package для каждого эпика (их немного, создаются по одному, чтобы получить их ID).

   • create_work_packages_bulk для пользовательских историй, используя parent_id соответствующего эпика для каждой.

5. Проверьте итоговый отчёт (что создано, что не удалось) и при необходимости исправьте в OpenProject.

Примечание: для создания токену требуется разрешение edit_work_packages (см. раздел о создании токена), а не только чтение.

📊 Варианты использования

1. Анализ проектов

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. Поиск задач

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. Отчёт по времени

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

4. Состояние проекта

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. Аудит изменений

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

🏗️ Архитектура

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

🔐 Безопасность

• ✅ Аутентификация по Bearer-токену (безопасно, не требует учётных данных в открытом виде)

• ✅ Валидация входных данных с помощью Zod (предотвращает инъекции)

• ✅ Детальная обработка ошибок (не раскрывает конфиденциальные данные)

• ✅ Строгий режим TypeScript (предотвращает ошибки типов)

• ⚠️ Токен хранится в .env — НЕ коммитьте этот файл в git

🚨 Устранение неполадок

"Authentication failed"

• Проверьте, что токен в .env действителен

• Создайте новый токен в OpenProject

"Connection error"

• Проверьте, что OPENPROJECT_URL доступен с вашей машины

• Если вы используете прокси/VPN, настройте переменные окружения прокси

"No projects found"

• Проверьте, что у вашего пользователя есть права на просмотр проектов

• Проверьте, что в вашем экземпляре существуют проекты

Сервер не запускается

npm run build
npm run dev

Проверьте вывод ошибок в терминале.

📈 Планируемые улучшения

• Поддержка создания/редактирования рабочих пакетов из Claude

• Поддержка комментариев к рабочим пакетам

• Интеграция с диаграммами Ганта

• Вебхуки для уведомлений в реальном времени

• Кэширование данных для повышения производительности

• Комплексные оценки (SEP)

📦 Распространение среди команды разработчиков

Каждому разработчику нужна собственная копия + собственный API-токен (никогда не делитесь токеном между несколькими людьми — действия фиксируются в аудите по пользователю в OpenProject).

Рекомендуемый вариант: общий Git-репозиторий

1. Загрузите эту папку в приватный репозиторий (GitHub org или Gitea/GitLab на linux.ie). Не забывайте, что .env уже в .gitignore — он никогда не загружается.

2. Каждый разработчик:

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

3. Каждый создаёт собственный токен (Administration → API & Webhooks → Personal Access Tokens, с разрешением edit_work_packages, если они будут создавать истории) и вставляет его в свой .env.

4. Каждый добавляет его в Claude Code (Settings → MCP Servers → Add Local Server), указывая на свой локальный dist/index.js.

Альтернатива без Git: сжатая папка

Если вы пока не хотите настраивать репозиторий, можно поделиться .zip папки (исключая node_modules, dist и .env), и каждый разработчик выполнит npm install && npm run build локально. Механика та же, меняется только способ распространения — CI/CD не требуется, потому что нет центрального сервера для развёртывания: MCP работает через stdio на машине каждого разработчика.

Если позже вы запустите его как общий удалённый сервер

Если вместо локального запуска каждым разработчиком вы предпочитаете единый сервер (например, на linux.ie), который используют все, тогда потребуется CI/CD (сборка + развёртывание при каждом push) и перенос транспорта с stdio на HTTP. Это значительный архитектурный переход — сообщите мне, если это тот путь, который вы хотите, и мы спланируем его отдельно.

🤝 Вклад в проект

Это сервер MCP с открытым исходным кодом. Чтобы улучшить его:

1. Сделайте форк репозитория

2. Создайте ветку для своей функции (git checkout -b feature/mi-feature)

3. Зафиксируйте изменения (git commit -am 'Agrego mi-feature')

4. Отправьте в ветку (git push origin feature/mi-feature)

5. Откройте Pull Request

📄 Лицензия

MIT — свободно используйте, изменяйте и распространяйте

💬 Поддержка

Чтобы сообщить об ошибках, задать вопросы или оставить предложения:

• Откройте issue в репозитории

• Ознакомьтесь с документацией MCP

• Изучите документацию OpenProject API

Создано с ❤️ для Integral de Empaques S.A.S.