MCP Server for OpenProject Weekly Reports

Overview

The MCP Server for OpenProject Weekly Reports is a small service that uses the Model Context Protocol (MCP) to assemble weekly project summaries from OpenProject data. It connects to your OpenProject instance, fetches issues, time entries, and status updates, and composes human-readable weekly reports that can be consumed by other services (email, Slack, dashboards) or displayed in a web UI.

This server is useful for teams that want to automate recurring reporting tasks and ensure consistent formatting and context in their reports. By exposing report generation as an MCP tool, you can integrate the same report-capability into LLM-driven workflows, pipelines, and other automation systems while keeping credentials and report templates configurable.

Features

• Fetches project data from OpenProject (work packages, statuses, time entries, custom fields)
• Aggregates and formats a weekly summary: progress, blockers, completed work, and upcoming items
• Exposes an MCP tool endpoint for LLMs and automated workflows to request reports
• Configurable templates and output formats (plain text, Markdown, JSON)
• Supports environment-based configuration and Docker deployment
• Includes example request/response contracts and minimal API for integration

Installation / Configuration

Prerequisites:

• Access to an OpenProject instance with an API token
• Docker (optional) or Node.js (if running locally)

Example environment variables (create a .env file):

OPENPROJECT_URL=https://openproject.example.com
OPENPROJECT_TOKEN=your_api_token_here
MCP_SERVER_PORT=8080
REPORT_TEMPLATE=weekly_template.md
MODEL_ENDPOINT=http://localhost:8081  # optional if integrating an LLM
OUTPUT_FORMAT=markdown                # json | markdown | text

Run locally (Node.js example):

# clone repo
git clone https://github.com/boma086/mcp-projectmanage-openproject.git
cd mcp-projectmanage-openproject

# install
npm install

# start (reads .env)
npm start

Run with Docker:

# docker-compose.yml (example)
version: '3.7'
services:
  mcp-openproject:
    image: yourorg/mcp-openproject:latest
    ports:
      - "8080:8080"
    environment:
      - OPENPROJECT_URL=${OPENPROJECT_URL}
      - OPENPROJECT_TOKEN=${OPENPROJECT_TOKEN}
      - MODEL_ENDPOINT=${MODEL_ENDPOINT}
      - OUTPUT_FORMAT=markdown

# start
docker-compose up -d

Configuration tips:

• Use a read-only API token scoped to the required projects.
• Tune REPORT_TEMPLATE to include the sections you need (completed, in-progress, blockers, hours).
• If integrating with an LLM, set MODEL_ENDPOINT to your inference service or leave unset to generate deterministic templates only.

Available Tools / Resources

The server exposes one primary MCP tool for report generation and several helper tools for fetching raw data.

Endpoints (HTTP / MCP mapping):

Sample request to generate a report:

POST /mcp/generate-weekly-report
Content-Type: application/json

{
  "project_id": 42,
  "week_start": "2026-04-06",
  "format": "markdown"
}

Sample response (truncated):

{
  "project_id": 42,
  "week_start": "2026-04-06",
  "format": "markdown",
  "report": "## Weekly Report (2026-04-06 to 2026-04-12)\n\n### Completed\n- Implemented API pagination (WP-123)\n\n### In Progress\n- Frontend integration (WP-130)\n\n### Blockers\n- Waiting on database migration window\n"
}

Resources included in the repo:

• Example report templates (Markdown)
• Minimal OpenProject client module
• Sample Dockerfile and docker-compose.yml
• API contract files for MCP integration

Use Cases

1. Automated weekly email to stakeholders

   • Schedule a job that calls POST /mcp/generate-weekly-report for each active project, then sends the returned markdown as an email body. This removes manual copy/paste of status updates.

2. LLM-assisted status synthesis

   • Use the MCP tool from an LLM-driven workflow: the LLM can call the generate tool to retrieve up-to-date project status and then ask follow-up questions or produce summaries tailored to different audiences.

3. Sprint / release retrospectives

   • Pull the aggregated work package list and time spent for a sprint date range (via fetch-time-entries), convert to a retrospective report, and attach to the release notes.

4. Dashboard ingestion

   • Produce JSON-format weekly summaries to feed into a BI or dashboard system, enabling historical trend charts (completed vs planned tasks, hours spent).

Quick Integration Examples

• Curl to generate a report:

curl -X POST "http://localhost:8080/mcp/generate-weekly-report" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 42, "week_start": "2026-04-06", "format":"json"}'

• Using the tool from an LLM workflow:
  • Register the MCP tool endpoint as a callable tool in your LLM orchestrator; the tool signature matches the JSON contract above, so models can request structured project summaries without direct API credentials.

Troubleshooting

• 401/403 from OpenProject: verify OPENPROJECT_TOKEN and token scope.
• Empty reports: check date ranges and that the project_id has activity for the week.
• Performance issues: limit fetched work packages with query parameters and paginate large projects.

For full source, examples, and template customization, see the GitHub repository: https://github.com/boma086/mcp-projectmanage-openproject.