OpenProject MCP Server

How to use

You will run one of two MCP server solutions for OpenProject and connect your MCP client to the provided MCP endpoint. Use the HTTP-based solution for production deployments and the FastAPI-based solution for development and testing. Your MCP client can request intelligent weekly or monthly reports, perform risk assessments, and analyze team workloads using predefined templates or your own custom templates.

Typical usage patterns include generating a weekly Japanese-style report for a project, assessing project risks, or obtaining workload optimization suggestions. You will point your MCP client at the MCP endpoint, authenticate with the configured API key, and invoke the appropriate tools through the MCP interface.

If you are using the HTTP solution, the MCP endpoint is available at the /mcp path on port 8010. If you are using the FastAPI solution, the MCP endpoint is available at the /mcp path on port 8020. The service health endpoints help you monitor the status of each server.

How to install

Prerequisites you need before installation: Python 3.x and a shell environment (Linux/macOS) or PowerShell (Windows). You may also use Docker Compose to start a local OpenProject instance.

# Start a local OpenProject instance (optional, using Docker Compose)
docker-compose up -d

# Open OpenProject in your browser
# URL: http://localhost:8090
# Default credentials: admin / admin

Choose and start one of the MCP solutions described below. Follow the corresponding steps to install dependencies, configure environment variables, and run the MCP server.

# Option 1: HTTP solution (recommended for production)
cd solution-http
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ../mcp-core

# Copy and edit environment configuration
cp .env.example .env
# Edit .env to set OpenProject URL and API Key

# Start the HTTP MCP service
python3 -m src.main

# Option 2: FastAPI solution (recommended for development)
cd solution-fastapi
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ../mcp-core

# Copy and edit environment configuration
cp .env.example .env
# Edit .env to set OpenProject URL and API Key

# Start the FastAPI MCP service
python app/main.py

Additional sections

Configuration and startup details are designed to be straightforward. The HTTP solution runs on port 8010 and exposes the MCP endpoint at /mcp. The FastAPI solution runs on port 8020 with the same endpoint path. Make sure to set the following environment variables in your .env file for each solution: OPENPROJECT_URL, OPENPROJECT_API_KEY, HOST, PORT, and LOG_LEVEL. Use the provided values or replace them with your own environment settings.

Environment variables you will configure: - OPENPROJECT_URL: URL of your OpenProject instance - OPENPROJECT_API_KEY: API key generated from OpenProject - HOST: host to bind the server (commonly 0.0.0.0) - PORT: port to listen on (8010 for HTTP solution, 8020 for FastAPI solution) - LOG_LEVEL: logging verbosity (INFO or DEBUG)

Template system supports multiple templates including professional Japanese-style weekly, monthly, and progress reports. You can customize templates via the web interface to align with your reporting standards.

You can integrate the MCP server with AI tools like Claude Desktop and Cursor by configuring the MCP endpoint as shown in the integration examples. Ensure your client can reach the MCP endpoint and that authentication is correctly configured.

For troubleshooting, verify that the MCP endpoint URL is reachable, the API key is valid, and the OpenProject URL is correctly configured. Check the logs for startup messages and runtime errors to identify misconfigurations quickly.

Notes

This MCP server supports both production-grade HTTP deployment and development-oriented FastAPI deployment. Choose the option that best fits your workload and testing needs. After setup, you will be able to generate instantaneous project reports, perform risk assessments, and optimize team workloads through a consistent MCP interface.

generate_report_from_template

Generates a report based on a selected template for a given project, enabling automated weekly, monthly, or progress reports.

assess_project_risks

Evaluates project risks using predefined criteria and returns risk levels and suggested mitigations.

analyze_workloads

Analyzes team member workloads and provides optimization recommendations.

template_editor

Allows creating and editing report templates through the web interface.

mcp_protocol

Provides MCP-compliant endpoints for integration with AI tools.