This OpenProject MCP Server enables AI assistants to manipulate OpenProject installations through a FastMCP-powered interface. It supports creating projects, adding work packages with start and due dates for Gantt charts, connecting dependencies between packages, and generating visual timelines within OpenProject. In the initial MVP phase, you can wire commands from your AI assistant to create projects, create work packages with dates, and establish dependencies to build a coherent project schedule. The Phase 1 enhancements introduce user management by email, dynamic loading of types/statuses/priorities, email-based assignment, project member viewing, enhanced validation, and improved caching/pagination for performance. When integrated with Claude Desktop or similar assistants, you can issue natural language instructions such as “create a new project for Q3 marketing” or “assign this task to user@example.com,” and the MCP server will translate them into OpenProject API calls. The integration supports both direct OpenProject operations and workflow steps that ensure a valid, end-to-end timeline in the project view.

Prerequisites:

• OpenProject instance (local or cloud) with an API key
• Python 3.8+ installed
• Access to a terminal or shell with git and Python tooling

Install steps:

1. Clone or download the repository: git clone https://github.com/firsthalfhero-openproject-mcp-server.git cd openproject-mcp-server

2. Create and activate a virtual environment: python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies: pip install -r requirements.txt

4. Configure environment variables: cp env.example .env

   Edit .env with your OpenProject details (URL and API key)

5. Run a quick test (optional): python3 scripts/test_mvp.py

6. Start the MCP server: python3 scripts/run_server.py

Notes:

• The server reads configuration from environment variables or the .env file. Ensure OPENPROJECT_URL and OPENPROJECT_API_KEY are set.
• If you plan to use Docker, refer to the Docker Deployment section in the README for containerized setup and port mapping.

Tips and common considerations:

• Ensure the OpenProject API key has sufficient permissions for project creation, work package management, and dependencies.
• Keep MCP_PORT consistent with Claude Desktop configuration to avoid connection issues.
• For production, consider enabling caching options and pagination controls described in the README to optimize performance with large OpenProject installations.
• When using Docker, always mount volumes for logs and data to preserve information between restarts.
• If you encounter port conflicts, verify both MCP and Claude Desktop configurations point to the same port and adjust deployments accordingly.
• The integration supports both local Python execution and Docker deployment; choose the option that best fits your workflow and security requirements.