OpenProject MCP Server

Claude를 OpenProject 인스턴스에 연결하기 위한 고품질 Model Context Protocol (MCP) 서버입니다. Claude가 대화에서 직접 프로젝트, 작업 패키지(work packages), 사용자, 시간 항목을 조회·검색·관리할 수 있게 해줍니다.

🚀 기능

✅ 프로젝트 접근 - 프로젝트 목록, 필터링, 상세 정보 조회
✅ 작업 패키지 관리 - 고급 필터링으로 작업, 버그, 기능 조회
✅ 전체 텍스트 검색 - 내용으로 작업 패키지 검색
✅ 활동 기록 - 작업 패키지의 변경 사항 및 댓글 확인
✅ 사용자 관리 - 사용자 목록 및 정보 조회
✅ 시간 항목 - 프로젝트, 사용자, 기간별 등록 시간 조회
✅ 스마트 페이지네이션 - 대용량 데이터 세트 지원
✅ 견고한 오류 처리 - 명확하고 실행 가능한 메시지
✅ 완전한 타입 지원 - 최대 타입 안전성을 위한 TypeScript

Related MCP server: OpenProject MCP Server

📋 사전 요구 사항

• Node.js 18+ 또는 Bun 1.0+

• API 접근이 가능한 OpenProject 13+ 인스턴스

• OpenProject API 토큰 (Settings에서 생성 가능)

🔧 설치

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

OpenProject에서 API 토큰 생성 방법:

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, optional): 페이지네이션용

• name_filter (string, optional): 이름으로 필터링

• status (enum: "active" | "archived", optional): 상태로 필터링

예시:

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

get_project

프로젝트의 전체 상세 정보를 가져옵니다.

매개변수:

• project_id (string | number): 프로젝트 ID 또는 식별자

📋 작업 패키지 (Tasks)

list_work_packages

고급 필터링으로 작업 패키지를 나열합니다.

매개변수:

• project_id (string | number, optional): 프로젝트로 필터링

• status (string, optional): 상태 (예: "Open", "In Progress")

• priority (string, optional): 우선순위

• assignee_id (number, optional): 담당 사용자

• search (string, optional): 텍스트 검색

• offset (number, optional): 페이지네이션

get_work_package

작업 패키지의 전체 상세 정보를 가져옵니다.

매개변수:

• work_package_id (number): 작업 패키지 ID

get_work_package_activities

변경 기록과 댓글을 가져옵니다.

매개변수:

• work_package_id (number): 작업 패키지 ID

search_work_packages

작업 패키지 전체 텍스트 검색.

매개변수:

• query (string, required): 검색어

• project_id (string | number, optional): 프로젝트로 제한

• status (string, optional): 상태로 필터링

• priority (string, optional): 우선순위로 필터링

👤 사용자

list_users

OpenProject의 모든 사용자를 나열합니다.

매개변수:

• offset (number, optional): 페이지네이션

get_user

특정 사용자의 상세 정보를 가져옵니다.

매개변수:

• user_id (number): 사용자 ID

⏱️ 시간 항목

list_time_entries

기간, 사용자, 프로젝트별 필터링으로 시간 항목을 나열합니다.

매개변수:

• work_package_id (number, optional): 작업 패키지로 필터링

• user_id (number, optional): 사용자로 필터링

• project_id (string | number, optional): 프로젝트로 필터링

• from_date (string, optional): 시작 날짜 (YYYY-MM-DD)

• to_date (string, optional): 종료 날짜 (YYYY-MM-DD)

• offset (number, optional): 페이지네이션

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, optional, Markdown)

• type_id (number, optional): list_project_types로 얻은 유형 ID

• parent_id (number, optional): 상위 에픽 ID

• priority_id, assignee_id, start_date, due_date (optional)

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 파일을 읽고, 에픽과 사용자 스토리를 식별한 다음, OpenProject의 X 프로젝트에 업로드해줘".

4. Claude는 일반적으로 수동으로 조정할 필요 없이 다음을 수행합니다:

   • 프로젝트에 대해 list_project_types를 호출하여 Epic 및 User Story의 type_id를 확인합니다.

   • 각 에픽에 대해 create_work_package를 호출합니다(수량이 적으므로 ID를 얻기 위해 하나씩 생성).

   • 각 스토리에 해당하는 에픽의 parent_id를 사용하여 create_work_packages_bulk로 사용자 스토리를 생성합니다.

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 strict mode (타입 오류 방지)

• ⚠️ 토큰은 .env에 저장됩니다 - 이 파일을 git에 커밋하지 마세요

🚨 문제 해결

"Authentication failed"

• .env의 토큰이 유효한지 확인합니다.

• OpenProject에서 새 토큰을 재생성합니다.

"Connection error"

• OPENPROJECT_URL이 사용자 머신에서 접근 가능한지 확인합니다.

• 프록시/VPN을 사용하는 경우 프록시 환경 변수를 설정합니다.

"No projects found"

• 사용자에게 프로젝트를 볼 수 있는 권한이 있는지 확인합니다.

• 인스턴스에 프로젝트가 존재하는지 확인합니다.

서버가 시작되지 않음

npm run build
npm run dev

터미널의 오류 출력을 확인합니다.

📈 향후 개선 사항

• Claude에서 작업 패키지 생성/편집 지원

• 작업 패키지 댓글 지원

• Gantt 차트 통합

• 실시간 알림을 위한 웹훅

• 성능 향상을 위한 데이터 캐시

• 종합 평가 (SEP)

📦 개발팀에 배포

각 개발자는 자체 사본 + 자체 API 토큰이 필요합니다 (여러 사람이 토큰을 공유하지 마세요 — 작업은 OpenProject에서 사용자별로 감사됩니다).

권장 옵션: 공유 Git 저장소

1. 이 폴더를 비공개 저장소(GitHub 조직 또는 linux.ie의 Gitea/GitLab)에 업로드합니다. .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. 각자 로컬 dist/index.js를 가리키도록 Claude Code(Settings → MCP Servers → Add Local Server)에 추가합니다.

Git 없는 대안: 압축 폴더

아직 저장소를 만들고 싶지 않다면 폴더의 .zip(node_modules, dist, .env 제외)을 공유하고 각 개발자가 로컬에서 npm install && npm run build를 실행하게 할 수 있습니다. 동일한 방식이며 배포 수단만 다릅니다 — 중앙 서버를 배포할 필요가 없으므로 CI/CD가 필요하지 않습니다: MCP는 각 개발자의 머신에서 stdio로 실행됩니다.

나중에 공유 원격 서버로 실행하는 경우

각 개발자가 로컬에서 실행하는 대신 모든 사람이 사용하는 단일 서버(예: linux.ie)를 선호한다면, 그때는 CI/CD(푸시마다 빌드 + 배포)가 적용되며 전송 방식을 stdio에서 HTTP로 마이그레이션해야 합니다. 이는 더 큰 아키텍처 전환입니다 — 이 방향을 원한다면 말씀해 주시고 별도로 계획하겠습니다.

🤝 기여

이것은 오픈 소스 MCP 서버입니다. 개선하려면:

1. 저장소를 포크합니다.

2. 기능을 위한 브랜치를 생성합니다 (git checkout -b feature/내-기능).

3. 변경 사항을 커밋합니다 (git commit -am '내-기능 추가').

4. 브랜치에 푸시합니다 (git push origin feature/내-기능).

5. Pull Request를 엽니다.

📄 라이선스

MIT - 자유롭게 사용, 수정, 배포하세요.

💬 지원

버그 신고, 질문 또는 제안:

• 저장소에 이슈를 엽니다.

• MCP 문서를 참조합니다.

• OpenProject API 문서를 확인합니다.

Integral de Empaques S.A.S.를 위해 ❤️로 제작됨