OpenProject MCP Server

Un servidor Model Context Protocol (MCP) de alta calidad para conectar Claude con tu instancia de OpenProject. Permite a Claude consultar, buscar y gestionar proyectos, paquetes de trabajo (work packages), usuarios y entradas de tiempo directamente desde conversaciones.

🚀 Características

✅ Acceso a Proyectos - Listar, filtrar y obtener detalles de proyectos
✅ Gestión de Work Packages - Ver tareas, bugs, features con filtrado avanzado
✅ Búsqueda de Texto Completo - Buscar paquetes de trabajo por contenido
✅ Historial de Actividades - Ver cambios y comentarios en trabajo packages
✅ Gestión de Usuarios - Listar y obtener información de usuarios
✅ Entradas de Tiempo - Consultar tiempo registrado por proyecto, usuario, período
✅ Paginación Inteligente - Soporte para grandes conjuntos de datos
✅ Manejo de Errores Robusto - Mensajes claros y ActionAbles
✅ Tipado Completo - TypeScript para máxima seguridad de tipos

📋 Requisitos Previos

• Node.js 18+ o Bun 1.0+
• Una instancia de OpenProject 13+ con acceso a API
• Un API Token de OpenProject (generable en Settings)

🔧 Instalación

1. Clonar o descargar el servidor

cd openproject-mcp-server

2. Instalar dependencias

npm install
# o con bun
bun install

3. Configurar variables de entorno

Copia .env.example a .env y completa los valores:

cp .env.example .env

Edita .env:

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

Cómo generar un API Token en OpenProject:

1. En OpenProject, ve a Administration → API & Webhooks → Personal Access Tokens
2. Haz clic en "+ New Personal Access Token"
3. Asigna un nombre descriptivo (ej. "Claude MCP")
4. Marca los permisos requeridos:
   • ✅ view_work_packages
   • ✅ view_projects
   • ✅ view_users
   • ✅ view_time_entries
   • ✅ edit_work_packages (si deseas crear/editar)
5. Copia el token generado a .env

4. Compilar el servidor

npm run build

🎯 Uso

Opción A: En Claude Code

1. Abre Claude Code

2. Ve a Settings → MCP Servers

3. Haz clic en + Add Local Server

4. Configura:

   • Name: openproject
   • Command: node
   • Arguments: ["path/to/openproject-mcp-server/dist/index.js"]
   • Environment Variables: Los valores de .env

5. Guarda y reconecta a Claude

Opción B: Ejecutar localmente para testing

npm run dev

Luego en otra terminal, usa el MCP Inspector:

npm run inspect

Esto abre una interfaz web donde puedes probar cada herramienta.

Opción C: En Claude.ai

1. Abre claude.ai/code
2. Ve a Settings → MCP Servers
3. Agrega un servidor remoto si desplegaste este servidor en un host accesible
4. Configura credenciales de acceso

🛠️ Herramientas Disponibles

📦 Proyectos

list_projects

Lista todos los proyectos con filtrado opcional.

Parámetros:

• offset (number, optional): Para paginación
• name_filter (string, optional): Filtrar por nombre
• status (enum: "active" | "archived", optional): Filtrar por estado

Ejemplo:

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

get_project

Obtiene detalles completos de un proyecto.

Parámetros:

• project_id (string | number): ID o identificador del proyecto

---

📋 Work Packages (Tareas)

list_work_packages

Lista paquetes de trabajo con filtrado avanzado.

Parámetros:

• project_id (string | number, optional): Filtrar por proyecto
• status (string, optional): Estado (ej. "Open", "In Progress")
• priority (string, optional): Prioridad
• assignee_id (number, optional): Asignado a usuario
• search (string, optional): Búsqueda de texto
• offset (number, optional): Paginación

get_work_package

Obtiene detalles completos de un work package.

Parámetros:

• work_package_id (number): ID del paquete de trabajo

get_work_package_activities

Obtiene el historial de cambios y comentarios.

Parámetros:

• work_package_id (number): ID del paquete de trabajo

search_work_packages

Búsqueda de texto completo en paquetes de trabajo.

Parámetros:

• query (string, required): Término de búsqueda
• project_id (string | number, optional): Limitar a proyecto
• status (string, optional): Filtrar por estado
• priority (string, optional): Filtrar por prioridad

---

👤 Usuarios

list_users

Lista todos los usuarios en OpenProject.

Parámetros:

• offset (number, optional): Paginación

get_user

Obtiene detalles de un usuario específico.

Parámetros:

• user_id (number): ID del usuario

---

⏱️ Entradas de Tiempo

list_time_entries

Lista entradas de tiempo con filtrado por período, usuario, proyecto.

Parámetros:

• work_package_id (number, optional): Filtrar por paquete de trabajo
• user_id (number, optional): Filtrar por usuario
• project_id (string | number, optional): Filtrar por proyecto
• from_date (string, optional): Fecha inicial (YYYY-MM-DD)
• to_date (string, optional): Fecha final (YYYY-MM-DD)
• offset (number, optional): Paginación

get_time_entry

Obtiene detalles de una entrada de tiempo.

Parámetros:

• time_entry_id (number): ID de la entrada de tiempo

---

✍️ Escritura (Crear Épicas e Historias de Usuario)

list_project_types

Lista los tipos de work package disponibles en un proyecto (Epic, User Story, Task, Bug...) con su ID. Úsala primero — los IDs de tipo varían entre instancias de OpenProject.

Parámetros:

• project_id (string | number): ID o identificador del proyecto

create_work_package

Crea un work package (Épica, Historia de Usuario, Tarea, etc.). Usa parent_id para colgar una Historia de Usuario bajo su Épica.

Parámetros:

• project_id (string | number)
• subject (string)
• description (string, optional, Markdown)
• type_id (number, optional): ID del tipo, obtenido con list_project_types
• parent_id (number, optional): ID de la Épica padre
• priority_id, assignee_id, start_date, due_date (optional)

create_work_packages_bulk

Crea varios work packages en una sola llamada (ideal para subir todas las Historias de Usuario extraídas de un Word). Cada item puede tener su propio parent_id, así que historias de distintas épicas pueden crearse en la misma llamada. Devuelve un reporte por item (éxito/error), no aborta el lote completo si una falla.

Parámetros:

• project_id (string | number)
• items (array, máx 100): cada uno con los mismos campos que create_work_package (menos project_id)

---

📋 Flujo: Subir Épicas e Historias de Usuario desde Word

Caso de uso típico del equipo: tienen historias de usuario redactadas en .docx y necesitan cargarlas a OpenProject respetando la relación Épica → Historia.

1. Genera tu API Token personal (cada developer usa el suyo, ver arriba) y configura tu .env local.
2. Abre la conversación con Claude y adjunta o referencia el archivo .docx con las épicas/historias (Claude puede leerlo directamente).
3. Pide a Claude: "Lee este Word, identifica las épicas y sus historias de usuario, y súbelas al proyecto X de OpenProject".
4. Claude normalmente hará, sin que tengas que orquestarlo manualmente:
   • list_project_types sobre el proyecto para saber el type_id de Epic y de User Story.
   • create_work_package para cada Épica (pocas, se hace una por una para tener sus IDs).
   • create_work_packages_bulk para las Historias de Usuario, usando el parent_id de la Épica correspondiente a cada una.
5. Revisa el reporte final (qué se creó, qué falló) y corrige en OpenProject si hace falta.

Nota: el token necesita el permiso edit_work_packages (ver sección de generación de token) para poder crear, no solo leer.

📊 Casos de Uso

1. Análisis de Proyectos

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. Búsqueda de Tareas

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. Reporte de Tiempo

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

4. Estado del Proyecto

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. Auditoría de Cambios

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

🏗️ Arquitectura

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

🔐 Seguridad

• ✅ Autenticación Bearer Token (segura, no requiere credenciales en texto plano)
• ✅ Validación de inputs con Zod (previene inyecciones)
• ✅ Manejo de errores granular (no expone datos sensibles)
• ✅ TypeScript strict mode (previene errores de tipo)
• ⚠️ El token se almacena en .env - NO comitas este archivo a git

🚨 Troubleshooting

"Authentication failed"

• Verifica que el token en .env es válido
• Regenera un token nuevo en OpenProject

"Connection error"

• Verifica que OPENPROJECT_URL es accesible desde tu máquina
• Si usas proxy/VPN, configura variables de entorno de proxy

"No projects found"

• Verifica que tu usuario tiene permisos para ver proyectos
• Verifica que existen proyectos en tu instancia

Server no inicia

npm run build
npm run dev

Revisa la salida de errores en la terminal.

📈 Próximas Mejoras

• [ ] Soporte para crear/editar work packages desde Claude
• [ ] Soporte para comentarios en work packages
• [ ] Integración con Gantt charts
• [ ] Webhooks para notificaciones en tiempo real
• [ ] Caché de datos para mejor performance
• [ ] Evaluaciones comprehensivas (SEP)

📦 Distribuir a tu equipo de desarrollo

Cada developer necesita su propia copia + su propio API Token (nunca compartir un token entre varias personas — las acciones quedan auditadas por usuario en OpenProject).

Opción recomendada: repo Git compartido

1. Sube esta carpeta a un repositorio privado (GitHub org o el Gitea/GitLab de linux.ie). No olvides que .env ya está en .gitignore — nunca se sube.
2. Cada developer:

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

3. Cada uno genera su propio token (Administration → API & Webhooks → Personal Access Tokens, con permiso edit_work_packages si van a crear historias) y lo pega en su .env.
4. Cada uno lo agrega en Claude Code (Settings → MCP Servers → Add Local Server) apuntando a su dist/index.js local.

Alternativa sin Git: carpeta comprimida

Si aún no quieres montar el repo, puedes compartir un .zip de la carpeta (excluyendo node_modules, dist y .env) y que cada dev haga npm install && npm run build localmente. Es la misma mecánica, solo cambia el medio de distribución — no requiere CI/CD porque no hay un servidor central que desplegar: el MCP corre en stdio en la máquina de cada developer.

Si más adelante lo corres como servidor remoto compartido

Si en vez de que cada dev lo corra localmente prefieres un único servidor (en linux.ie, por ejemplo) que todos consuman, ahí sí aplica CI/CD (build + deploy en cada push) y habría que migrar el transporte de stdio a HTTP. Es un salto de arquitectura mayor — dímelo si es el camino que quieres y lo planeamos aparte.

🤝 Contribuir

Este es un servidor MCP de código abierto. Para mejorar:

1. Haz fork del repositorio
2. Crea una rama para tu feature (git checkout -b feature/mi-feature)
3. Commitea cambios (git commit -am 'Agrego mi-feature')
4. Push a la rama (git push origin feature/mi-feature)
5. Abre un Pull Request

📄 Licencia

MIT - Siéntete libre de usar, modificar y distribuir

💬 Soporte

Para reportar bugs, hacer preguntas o sugerencias:

• Abre un issue en el repositorio
• Consulta la documentación de MCP
• Revisa la documentación de OpenProject API

---

Creado con ❤️ para Integral de Empaques S.A.S.