This MCP server provides a bridge to the OpenProject API v3, exposing a set of actions that let you manage projects, work packages, and related metadata from your LLM or other MCP clients. After starting the server, you can invoke tools such as test_connection to verify connectivity, list_projects to fetch accessible projects, list_work_packages to query work packages with optional filters, and create_work_package to programmatically create new work items. Other utilities let you list types, users, memberships, statuses, and priorities, as well as get, update, or delete specific work packages and to manage time entries. The server authenticates requests using an OpenProject API key and supports optional HTTP proxy and configurable logging to fit into your deployment environment.

Prerequisites:

• Python 3.10 or higher
• uv (optional, for faster local startup) or you can run with plain python
• An OpenProject instance and an API key

Installation steps:

1. Install uv (optional):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\" 

Alternative (using pip)

pip install uv

2. Clone the repository (replace with your actual repo URL):

git clone https://github.com/yourusername/openproject-mcp.git
cd openproject-mcp

3. Create and activate a virtual environment (optional but recommended):

# If using venv
python -m venv .venv
# Activate (Unix/macOS)
source .venv/bin/activate
# Activate (Windows)
.venv\Scripts\activate

4. Install dependencies:

pip install -r requirements.txt

5. Configure environment variables (see next section) or create an .env file with the following keys:

OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_KEY=your-api-key-here
OPENPROJECT_PROXY=http://proxy.example.com:8080  # optional
LOG_LEVEL=INFO  # optional
TEST_CONNECTION_ON_STARTUP=true  # optional

6. Run the MCP server:

python openproject-mcp.py

Note: If you renamed the main script from openproject_mcp_server.py, update the command accordingly.

Notes and tips:

• Ensure OPENPROJECT_URL and OPENPROJECT_API_KEY are set correctly; otherwise, API calls will fail.
• If you're behind a proxy, set OPENPROJECT_PROXY to route requests through it.
• The server supports configurable LOG_LEVEL to help with debugging (DEBUG/INFO/WARNING/ERROR).
• On startup you can enable TEST_CONNECTION_ON_STARTUP to verify connectivity automatically.
• If you modify the script name or path, update the instructions in the Usage section accordingly.
• For Claude Desktop integration, you can point your MCP server entry to the python path of your virtual environment to improve reliability, or use uv with the appropriate path as shown in the README.
• OpenProject API v3 endpoints may require specific permissions; ensure the API key has access to the data you intend to query or modify.