OpenProject

You can run an OpenProject MCP Server that lets an AI assistant create and manage OpenProject projects, work packages, and Gantt charts. It exposes a practical API through a local MCP server so you can automate planning and tracking directly from your AI workflows.

How to use

To connect an MCP client, run the server locally and point your client to the MCP endpoint. The server provides tools to create projects, add work packages with dates for Gantt charts, and establish dependencies so you get a complete visual timeline in OpenProject. You can also manage users by email, load dynamic configuration (types, statuses, priorities), and assign work packages via email.

How to install

Prerequisites you need before starting:

• OpenProject instance (local or cloud)
• OpenProject API key
• Python 3.8+

Steps to install the MCP server locally:

cd openproject-mcp-server

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install -r requirements.txt

cp env.example .env
# Edit .env with your OpenProject details

Additional configuration and usage notes

Configure environment variables in your .env file to point to your OpenProject instance and authentication details. The following variables are used by the MCP server:

OPENPROJECT_URL=http://localhost:3000
OPENPROJECT_API_KEY=your_40_character_api_key_here
MCP_HOST=localhost
MCP_PORT=8080
MCP_LOG_LEVEL=INFO
OPENPROJECT_CACHE_TIMEOUT_MINUTES=5
OPENPROJECT_PAGINATION_SIZE=100
OPENPROJECT_MAX_RETRIES=3

Testing before production

Test connectivity and basic capabilities to ensure your setup works with your OpenProject instance.

python3 scripts/test_mvp.py

Running the server

Start the MCP server when you are ready to connect your AI assistant.

python3 scripts/run_server.py

Docker deployment (recommended for production)

Docker deployment is the recommended production method. You can deploy with a single port or customize ports to match your Claude Desktop configuration.

Environment variables used in Docker deployments are defined in a .env file and loaded into the container.

Typical deployment commands use the provided scripts or standard Docker commands. Ensure your MCP port matches your client configuration.

Troubleshooting tips

If you run into connection or permission issues, verify the OpenProject URL, API key length, and that the API is reachable. For date-related problems, use the YYYY-MM-DD format and ensure due dates come after start dates.

Security and maintenance notes

Keep your API key secret, store credentials in the .env file, and use Docker health checks and restart policies for production stability.

Related concepts for daily use

Once connected, you can create projects, add work packages with dates, link dependencies for Gantt charts, and manage users by email to streamline assignments.

Available tools

create_project

Create a new project in OpenProject with a name and optional description.

create_work_package

Create a work package with dates and optional assignee, description, and relationships to support Gantt chart timelines.

create_work_package_dependency

Create dependencies between work packages to model task order in a Gantt chart.

get_work_package_relations

Retrieve all relations for a specific work package to inspect dependencies.

delete_work_package_relation

Remove a specific work package relation by ID.

get_users

List users with optional email filtering to support dynamic assignment.

assign_work_package_by_email

Assign a work package to a user by email address.

get_project_members

List project members with their roles and permissions.

get_work_package_types

Fetch available work package types from the OpenProject instance.

get_work_package_statuses

Fetch available work package statuses from the OpenProject instance.

get_priorities

Fetch available work package priorities from the OpenProject instance.

get_projects

List all projects in the OpenProject instance.

get_work_packages

Retrieve work packages for a specific project.

update_work_package

Update an existing work package with new details.

get_project_summary

Generate a comprehensive overview of a project with metrics.