Skip to content
Back to search

openproject-mcp-server

A Model Context Protocol (MCP) server that provides seamless integration with OpenProject API v3.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/andyeverything--openproject-mcp-server/badge.svg)](/listings/andyeverything--openproject-mcp-server)

HTML

<a href="/listings/andyeverything--openproject-mcp-server"><img src="/api/listings/andyeverything--openproject-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Install uv (if not already installed)

**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 and Setup the Project

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

3. Create Virtual Environment and Install Dependencies

# Create virtual environment and install dependencies in one command
uv sync

**Alternative (manual steps):**

# Create virtual environment
uv venv

# Install dependencies
uv pip install -r requirements.txt

4. Configure Environment

# Copy the environment template
cp env_example.txt .env

Edit `.env` and add your OpenProject configuration:

OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_KEY=your-api-key-here

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 988 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/andyeverything-openproject-mcp-server-badge.png)](https://mseep.ai/app/andyeverything-openproject-mcp-server)
  2. <br>![status](https://img.shields.io/badge/status-WIP-yellow) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)<br><br>⚠️ This is an early-stage project. Do not use it productively – contributions welcome!<br>
  3. # OpenProject MCP Server
  4. A Model Context Protocol (MCP) server that provides seamless integration with [OpenProject](https://www.openproject.org/) API v3. This server enables LLM applications to interact with OpenProject for project management, work package tracking, and task creation.
  5. ## Features
  6. - 🔌 **Full OpenProject API v3 Integration**
  7. - 📋 **Project Management**: List and filter projects
  8. - 📝 **Work Package Management**: Create, list, and filter work packages
  9. - 🏷️ **Type Management**: List available work package types
  10. - 🔐 **Secure Authentication**: API key-based authentication
  11. - 🌐 **Proxy Support**: Optional HTTP proxy configuration
  12. - 🚀 **Async Operations**: Built with modern async/await patterns
  13. - 📊 **Comprehensive Logging**: Configurable logging levels
  14. ## Prerequisites
  15. - Python 3.10 or higher
  16. - [uv](https://docs.astral.sh/uv/) (fast Python package manager)
  17. - An OpenProject instance (cloud or self-hosted)
  18. - OpenProject API key (generated from your user profile)
  19. ## Installation
  20. ### 1. Install uv (if not already installed)
  21. **macOS/Linux:**
  22. ```bash
  23. curl -LsSf https://astral.sh/uv/install.sh | sh
  24. ```
  25. **Windows:**
  26. ```powershell
  27. powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  28. ```
  29. **Alternative (using pip):**
  30. ```bash
  31. pip install uv
  32. ```
  33. ### 2. Clone and Setup the Project
  34. ```bash
  35. git clone https://github.com/yourusername/openproject-mcp.git
  36. cd openproject-mcp
  37. ```
  38. ### 3. Create Virtual Environment and Install Dependencies
  39. ```bash
  40. # Create virtual environment and install dependencies in one command
  41. uv sync
  42. ```
  43. **Alternative (manual steps):**
  44. ```bash
  45. # Create virtual environment
  46. uv venv
  47. # Install dependencies
  48. uv pip install -r requirements.txt
  49. ```
  50. ### 4. Configure Environment
  51. ```bash
  52. # Copy the environment template
  53. cp env_example.txt .env
  54. ```
  55. Edit `.env` and add your OpenProject configuration:
  56. ```env
  57. OPENPROJECT_URL=https://your-instance.openproject.com
  58. OPENPROJECT_API_KEY=your-api-key-here
  59. ```
  60. ## Configuration
  61. ### Environment Variables
  62. | Variable | Required | Description | Example |
  63. |----------|----------|-------------|---------|
  64. | `OPENPROJECT_URL` | Yes | Your OpenProject instance URL | `https://mycompany.openproject.com` |
  65. | `OPENPROJECT_API_KEY` | Yes | API key from your OpenProject user profile | `8169846b42461e6e...` |
  66. | `OPENPROJECT_PROXY` | No | HTTP proxy URL if needed | `http://proxy.company.com:8080` |
  67. | `LOG_LEVEL` | No | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` |
  68. | `TEST_CONNECTION_ON_STARTUP` | No | Test API connection when server starts | `true` |
  69. ### Getting an API Key
  70. 1. Log in to your OpenProject instance
  71. 2. Go to **My account** (click your avatar)
  72. 3. Navigate to **Access tokens**
  73. 4. Click **+ Add** to create a new token
  74. 5. Give it a name and copy the generated token
  75. ## Usage
  76. ### Deployment Options
  77. This MCP server can be deployed in two ways:
  78. 1. **Local (stdio)**: Run on your local machine for personal use
  79. 2. **Cloud (SSE)**: Deploy to FastMCP Cloud for team/organization access
  80. ### Option 1: Local Deployment (stdio)
  81. #### Running the Server
  82. **Using uv (recommended):**
  83. ```bash
  84. uv run python openproject-mcp-fastmcp.py
  85. ```
  86. **Alternative (manual activation):**
  87. ```bash
  88. # Activate virtual environment
  89. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  90. # Run the server
  91. python openproject-mcp-fastmcp.py
  92. ```
  93. **File Structure:**
  94. - `openproject-mcp-fastmcp.py` - Stdio transport (for local Claude Desktop)
  95. - `openproject-mcp-sse.py` - SSE transport (for FastMCP Cloud)
  96. - `src/` - Core implementation using FastMCP framework
  97. - `src/server.py` - FastMCP server initialization
  98. - `src/client.py` - OpenProject API client
  99. - `src/tools/` - All 40+ MCP tools organized by category
  100. #### Integration with Claude Desktop
  101. **Quick Install Using CLI (Recommended):**
  102. This command works for both **Claude Desktop** and **Claude Code (VSCode extension)**.
  103. ```powershell
  104. # Windows - Replace <YOUR_PROJECT_PATH> with your actual path
  105. claude mcp add openproject-fastmcp "<YOUR_PROJECT_PATH>\.venv\Scripts\python.exe" "<YOUR_PROJECT_PATH>\openproject-mcp-fastmcp.py" -e "PYTHONPATH=<YOUR_PROJECT_PATH>" -e "OPENPROJECT_URL=https://your-instance.com" -e "OPENPROJECT_API_KEY=your-api-key"
  106. ```
  107. ```bash
  108. # macOS/Linux - Replace <YOUR_PROJECT_PATH> with your actual path
  109. claude mcp add openproject-fastmcp "<YOUR_PROJECT_PATH>/.venv/bin/python" "<YOUR_PROJECT_PATH>/openproject-mcp-fastmcp.py" -e "PYTHONPATH=<YOUR_PROJECT_PATH>" -e "OPENPROJECT_URL=https://your-instance.com" -e "OPENPROJECT_API_KEY=your-api-key"
  110. ```
  111. **Example (Windows):**
  112. ```powershell
  113. # If you cloned the project to C:\Users\YourName\openproject-mcp-server
  114. claude mcp add openproject-fastmcp "C:\Users\YourName\openproject-mcp-server\.venv\Scripts\python.exe" "C:\Users\YourName\openproject-mcp-server\openproject-mcp-fastmcp.py" -e "PYTHONPATH=C:\Users\YourName\openproject-mcp-server" -e "OPENPROJECT_URL=https://manage.example.com" -e "OPENPROJECT_API_KEY=abc123xyz456"
  115. ```
  116. **Example (macOS/Linux):**
  117. ```bash
  118. # If you cloned the project to /home/yourname/openproject-mcp-server
  119. claude mcp add openproject-fastmcp "/home/yourname/openproject-mcp-server/.venv/bin/python" "/home/yourname/openproject-mcp-server/openproject-mcp-fastmcp.py" -e "PYTHONPATH=/home/yourname/openproject-mcp-server" -e "OPENPROJECT_URL=https://manage.example.com" -e "OPENPROJECT_API_KEY=abc123xyz456"
  120. ```
  121. **Important:** Replace the following values:
  122. - `<YOUR_PROJECT_PATH>` with your actual installation directory
  123. - `https://your-instance.com` with your OpenProject URL
  124. - `your-api-key` with your API key from Account Settings
  125. **Verify Installation:**
  126. ```powershell
  127. claude mcp list
  128. ```
  129. You should see:
  130. ```
  131. openproject-fastmcp: ... - ✓ Connected
  132. ```
  133. After running the command, restart Claude Desktop or reload VSCode window.
  134. ---
  135. **Manual Configuration:**
  136. Add this configuration to your Claude Desktop config file:
  137. **Config file locations:**
  138. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  139. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  140. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  141. **Windows Configuration:**
  142. ```json
  143. {
  144. "mcpServers": {
  145. "openproject-fastmcp": {
  146. "command": "D:\\Promete\\Project\\mcp-openproject\\openproject-mcp-server\\.venv\\Scripts\\python.exe",
  147. "args": ["D:\\Promete\\Project\\mcp-openproject\\openproject-mcp-server\\openproject-mcp-fastmcp.py"],
  148. "env": {
  149. "PYTHONPATH": "D:\\Promete\\Project\\mcp-openproject\\openproject-mcp-server",
  150. "OPENPROJECT_URL": "https://your-instance.com",
  151. "OPENPROJECT_API_KEY": "your-api-key"
  152. }
  153. }
  154. }
  155. }
  156. ```
  157. **macOS/Linux Configuration:**
  158. ```json
  159. {
  160. "mcpServers": {
  161. "openproject-fastmcp": {
  162. "command": "/path/to/project/.venv/bin/python",
  163. "args": ["/path/to/project/openproject-mcp-fastmcp.py"],
  164. "env": {
  165. "PYTHONPATH": "/path/to/project",
  166. "OPENPROJECT_URL": "https://your-instance.com",
  167. "OPENPROJECT_API_KEY": "your-api-key"
  168. }
  169. }
  170. }
  171. }
  172. ```
  173. **Note:** Using environment variables in config is more secure than storing credentials in `.env` file.
  174. **Verification:**
  175. Check if the server is connected:
  176. ```powershell
  177. claude mcp list
  178. ```
  179. You should see:
  180. ```
  181. openproject-fastmcp: ... - ✓ Connected
  182. ```
  183. If you see `✗ Failed to connect`, check:
  184. 1. Python path is correct
  185. 2. `openproject-mcp-fastmcp.py` file exists
  186. 3. Environment variables are set correctly
  187. 4. Restart Claude Desktop after configuration changes
  188. ### Option 2: Cloud Deployment (FastMCP Cloud) ☁️
  189. Deploy to FastMCP Cloud for centralized access across your organization. This eliminates the need for each user to install Python and run the server locally.
  190. **Benefits:**
  191. - No local installation required for end users
  192. - Centralized API key and configuration management
  193. - Access from anywhere with internet
  194. - Automatic scaling and monitoring
  195. - Team collaboration features
  196. **Quick Start:**
  197. 1. **Ensure you have the SSE entry point:**
  198. ```bash
  199. # The project includes openproject-mcp-sse.py for cloud deployment
  200. ls openproject-mcp-sse.py
  201. ```
  202. 2. **Create/update .fastmcp.yaml config:**
  203. ```yaml
  204. name: openproject-mcp
  205. version: "1.0.0"
  206. description: "OpenProject MCP Server for Claude Desktop"
  207. entry_point: openproject-mcp-sse.py
  208. runtime:
  209. python_version: "3.11"
  210. environment:
  211. - OPENPROJECT_URL
  212. - OPENPROJECT_API_KEY
  213. - OPENPROJECT_PROXY
  214. ```
  215. 3. **Deploy to FastMCP Cloud:**
  216. ```bash
  217. # Install FastMCP CLI (if not installed)
  218. pip install fastmcp
  219. # Login to FastMCP Cloud
  220. fastmcp login
  221. # Deploy your server
  222. fastmcp deploy
  223. ```
  224. 4. **Configure environment variables** on FastMCP Cloud dashboard:
  225. - `OPENPROJECT_URL`: Your OpenProject instance URL
  226. - `OPENPROJECT_API_KEY`: Your API key
  227. - `OPENPROJECT_PROXY`: (Optional) Proxy URL if needed
  228. 5. **Users connect via Claude Desktop** with SSE transport:
  229. ```json
  230. {
  231. "mcpServers": {
  232. "openproject": {
  233. "url": "https://mcp.fastmcp.com/sse/openproject-mcp",
  234. "transport": "sse"
  235. }
  236. }
  237. }
  238. ```
  239. **📚 Detailed Documentation:**
  240. - [Quick Start Guide](QUICK_START_CLOUD.md) - Fast setup in 5 minutes
  241. - [FastMCP Cloud Deployment Guide (English)](FASTMCP_CLOUD_DEPLOYMENT.md) - Comprehensive guide
  242. - [Hướng dẫn kết nối Cloud (Tiếng Việt)](HUONG_DAN_KET_NOI_CLOUD.md) - Vietnamese guide
  243. For comprehensive deployment instructions, troubleshooting, and best practices, see the guides above.
  244. ### Available Tools
  245. #### 1. `test_connection`
  246. Test the connection to your OpenProject instance.
  247. **Example:**
  248. ```
  249. Test the OpenProject connection
  250. ```
  251. #### 2. `list_projects`
  252. List all projects you have access to.
  253. **Parameters:**
  254. - `active_only` (boolean, optional): Show only active projects (default: true)
  255. **Example:**
  256. ```
  257. List all active projects
  258. ```
  259. #### 3. `list_work_packages` ⭐ ENHANCED
  260. List work packages with advanced filtering capabilities - the most powerful search tool.
  261. **Basic Parameters:**
  262. - `project_id` (integer, optional): Filter by project
  263. - `assignee_id` (integer, optional): Filter by assignee
  264. - `active_only` (boolean, optional): Only open tasks (default: true)
  265. - `offset` (integer, optional): Pagination offset (default: 0)
  266. - `page_size` (integer, optional): Results per page (default: 20, max: 100)
  267. **Advanced Filters (NEW - 18 parameters):**
  268. - `priority_ids` (string, optional): Comma-separated priority IDs (e.g., "3,4")
  269. - `type_ids` (string, optional): Comma-separated type IDs (e.g., "1,2")
  270. - `status_ids` (string, optional): Comma-separated status IDs (overrides active_only)
  271. - `version_ids` (string, optional): Comma-separated version/sprint IDs
  272. - `due_before` (string, optional): Due before date (YYYY-MM-DD)
  273. - `due_after` (string, optional): Due after date (YYYY-MM-DD)
  274. - `created_after` (string, optional): Created after date (YYYY-MM-DD)
  275. - `updated_after` (string, optional): Updated after date (YYYY-MM-DD)
  276. - `unassigned_only` (boolean, optional): Only unassigned tasks
  277. - `overdue_only` (boolean, optional): Only overdue tasks
  278. - `percentage_done_min` (integer, optional): Min completion % (0-100)
  279. - `percentage_done_max` (integer, optional): Max completion % (0-100)
  280. - `author_id` (integer, optional): Filter by task creator
  281. - `parent_id` (integer, optional): Child tasks of parent
  282. - `no_parent_only` (boolean, optional): Only top-level tasks
  283. **Features:**
  284. - **23 total parameters** for ultimate flexibility
  285. - All filters use AND logic
  286. - 100% backward compatible
  287. - Smart filter priority (e.g., status_ids > active_only)
  288. **Examples:**
  289. ```
  290. Find high-priority bugs due this week in project 5
  291. ```
  292. ```
  293. Find overdue unassigned tasks
  294. ```
  295. ```
  296. Show tasks 50-80% complete
  297. ```
  298. #### 4. `search_work_packages`
  299. Search work packages by subject or ID using server-side filtering.
  300. **Parameters:**
  301. - `query` (string, required): Search text to match against work package subject or ID
  302. - `project_id` (integer, optional): Limit search to a specific project
  303. - `active_only` (boolean, optional): Search only open work packages (default: true)
  304. - `offset` (integer, optional): Starting index for pagination (default: 0)
  305. - `page_size` (integer, optional): Number of results per page (default: 20, max: 100)
  306. **Example:**
  307. ```
  308. Search for tasks containing "login"
  309. ```
  310. ```
  311. Search for work package by ID: "123"
  312. ```
  313. **Note:** This tool provides fast search without needing to paginate through all tasks. Use this when you need to find specific tasks by name or ID.
  314. #### 5. `list_types`
  315. List available work package types.
  316. **Parameters:**
  317. - `project_id` (integer, optional): Filter types by project
  318. **Example:**
  319. ```
  320. List all work package types
  321. ```
  322. #### 6. `create_work_package`
  323. Create a new work package.
  324. **Parameters:**
  325. - `project_id` (integer, required): The project ID
  326. - `subject` (string, required): Work package title
  327. - `type_id` (integer, required): Type ID (e.g., 1 for Task)
  328. - `description` (string, optional): Description in Markdown format
  329. - `priority_id` (integer, optional): Priority ID
  330. - `assignee_id` (integer, optional): User ID to assign to
  331. **Example:**
  332. ```
  333. Create a new task in project 5 titled "Update documentation" with type ID 1
  334. ```
  335. #### 7. `list_users`
  336. List all users in the OpenProject instance.
  337. **Parameters:**
  338. - `active_only` (boolean, optional): Show only active users (default: true)
  339. #### 8. `get_user`
  340. Get detailed information about a specific user.
  341. **Parameters:**
  342. - `user_id` (integer, required): User ID
  343. #### 9. `list_memberships`
  344. List project memberships showing users and their roles.
  345. **Parameters:**
  346. - `project_id` (integer, optional): Filter by specific project
  347. - `user_id` (integer, optional): Filter by specific user
  348. #### 10. `list_statuses`
  349. List all available work package statuses.
  350. #### 11. `list_priorities`
  351. List all available work package priorities.
  352. #### 12. `get_work_package`
  353. Get detailed information about a specific work package.
  354. **Parameters:**
  355. - `work_package_id` (integer, required): Work package ID
  356. #### 13. `update_work_package`
  357. Update an existing work package.
  358. **Parameters:**
  359. - `work_package_id` (integer, required): Work package ID
  360. - `subject` (string, optional): Work package title
  361. - `description` (string, optional): Description in Markdown format
  362. - `type_id` (integer, optional): Type ID
  363. - `status_id` (integer, optional): Status ID
  364. - `priority_id` (integer, optional): Priority ID
  365. - `assignee_id` (integer, optional): User ID to assign to
  366. - `percentage_done` (integer, optional): Completion percentage (0-100)
  367. #### 13. `delete_work_package`
  368. Delete a work package.
  369. **Parameters:**
  370. - `work_package_id` (integer, required): Work package ID
  371. ### Advanced Filters 🔍
  372. The following tools provide specialized filtering capabilities for common work package search scenarios. All tools support flexible filtering by project, assignee, priority, and type.
  373. #### 14. `list_overdue_work_packages`
  374. List all work packages that are past their due date.
  375. **Parameters:**
  376. - `project_id` (integer, optional): Filter by project
  377. - `assignee_id` (integer, optional): Filter by assignee
  378. - `priority_ids` (string, optional): Comma-separated priority IDs (e.g., "3,4")
  379. - `type_ids` (string, optional): Comma-separated type IDs (e.g., "1,2")
  380. - `page_size` (integer, optional): Results per page (default: 50, max: 100)
  381. **Features:**
  382. - Shows "X days overdue" for each task
  383. - Sorted by most overdue first
  384. - Only searches open (non-closed) tasks
  385. **Example:**
  386. ```
  387. Find all overdue high-priority tasks in project 5
  388. ```
  389. #### 15. `list_work_packages_due_soon`
  390. List work packages due within the next N days.
  391. **Parameters:**
  392. - `days` (integer, optional): Days to look ahead (default: 7, max: 365)
  393. - `project_id` (integer, optional): Filter by project
  394. - `assignee_id` (integer, optional): Filter by assignee
  395. - `priority_ids` (string, optional): Comma-separated priority IDs
  396. - `page_size` (integer, optional): Results per page (default: 50, max: 100)
  397. **Features:**
  398. - Shows "Due in X days", "Due tomorrow", or "Due today!"
  399. - Sorted by soonest first
  400. - Configurable lookahead period
  401. **Example:**
  402. ```
  403. Show me tasks due in the next 3 days
  404. ```
  405. #### 16. `list_unassigned_work_packages`
  406. List work packages that have no assignee.
  407. **Parameters:**
  408. - `project_id` (integer, optional): Filter by project
  409. - `priority_ids` (string, optional): Comma-separated priority IDs
  410. - `type_ids` (string, optional): Comma-separated type IDs
  411. - `active_only` (boolean, optional): Only open tasks (default: true)
  412. - `page_size` (integer, optional): Results per page (default: 50, max: 100)
  413. **Features:**
  414. - Identifies tasks needing assignment
  415. - Useful for sprint planning
  416. - Supports priority and type filtering
  417. **Example:**
  418. ```
  419. Find unassigned high-priority bugs in project 5
  420. ```
  421. #### 17. `list_work_packages_created_recently`
  422. List work packages created in the last N days.
  423. **Parameters:**
  424. - `days` (integer, optional): Days to look back (default: 7, max: 365)
  425. - `project_id` (integer, optional): Filter by project
  426. - `assignee_id` (integer, optional): Filter by assignee
  427. - `type_ids` (string, optional): Comma-separated type IDs
  428. - `active_only` (boolean, optional): Only open tasks (default: true)
  429. - `page_size` (integer, optional): Results per page (default: 50, max: 100)
  430. **Features:**
  431. - Track new task creation patterns
  432. - Sorted by newest first
  433. - Configurable lookback period
  434. **Example:**
  435. ```
  436. Show bugs created in the last 3 days
  437. ```
  438. #### 18. `list_high_priority_work_packages`
  439. List work packages with high priority.
  440. **Parameters:**
  441. - `project_id` (integer, optional): Filter by project
  442. - `assignee_id` (integer, optional): Filter by assignee
  443. - `type_ids` (string, optional): Comma-separated type IDs
  444. - `active_only` (boolean, optional): Only open tasks (default: true)
  445. - `page_size` (integer, optional): Results per page (default: 50, max: 100)
  446. **Features:**
  447. - Assumes priority ID 3 = "High" (typical default)
  448. - Includes helpful note about using `list_priorities` if needed
  449. - Quick access to urgent tasks
  450. **Example:**
  451. ```
  452. Show all high-priority tasks in project 5
  453. ```
  454. **Note:** If your OpenProject instance uses different priority IDs, use `list_priorities` to find the correct ID, then use the enhanced `list_work_packages` with specific `priority_ids` parameter.
  455. #### 19. `list_work_packages_nearly_complete`
  456. List work packages that are nearly complete (high percentage done).
  457. **Parameters:**
  458. - `project_id` (integer, optional): Filter by project
  459. - `assignee_id` (integer, optional): Filter by assignee
  460. - `min_percentage` (integer, optional): Minimum completion % (default: 80, range: 1-99)
  461. - `active_only` (boolean, optional): Only open tasks (default: true)
  462. - `page_size` (integer, optional): Results per page (default: 50, max: 100)
  463. **Features:**
  464. - Find tasks needing final push
  465. - Sorted by highest percentage first
  466. - Includes completion summary section
  467. - Useful for sprint reviews
  468. **Example:**
  469. ```
  470. Show tasks more than 90% complete
  471. ```
  472. #### 20. `list_time_entries`
  473. List time entries with optional filtering.
  474. **Parameters:**
  475. - `work_package_id` (integer, optional): Filter by specific work package
  476. - `user_id` (integer, optional): Filter by specific user
  477. #### 15. `create_time_entry`
  478. Create a new time entry.
  479. **Parameters:**
  480. - `work_package_id` (integer, required): Work package ID
  481. - `hours` (number, required): Hours spent (e.g., 2.5)
  482. - `spent_on` (string, required): Date when time was spent (YYYY-MM-DD format)
  483. - `comment` (string, optional): Comment/description
  484. - `activity_id` (integer, optional): Activity ID
  485. #### 16. `update_time_entry`
  486. Update an existing time entry.
  487. **Parameters:**
  488. - `time_entry_id` (integer, required): Time entry ID
  489. - `hours` (number, optional): Hours spent
  490. - `spent_on` (string, optional): Date when time was spent
  491. - `comment` (string, optional): Comment/description
  492. - `activity_id` (integer, optional): Activity ID
  493. #### 17. `delete_time_entry`
  494. Delete a time entry.
  495. **Parameters:**
  496. - `time_entry_id` (integer, required): Time entry ID
  497. #### 18. `list_time_entry_activities`
  498. List available time entry activities.
  499. #### 19. `list_versions`
  500. List project versions/milestones.
  501. **Parameters:**
  502. - `project_id` (integer, optional): Filter by specific project
  503. #### 20. `create_version`
  504. Create a new project version/milestone.
  505. **Parameters:**
  506. - `project_id` (integer, required): Project ID
  507. - `name` (string, required): Version name
  508. - `description` (string, optional): Version description
  509. - `start_date` (string, optional): Start date (YYYY-MM-DD format)
  510. - `end_date` (string, optional): End date (YYYY-MM-DD format)
  511. - `status` (string, optional): Version status (open, locked, closed)
  512. #### 21. `create_project`
  513. Create a new project.
  514. **Parameters:**
  515. - `name` (string, required): Project name
  516. - `identifier` (string, required): Project identifier (unique)
  517. - `description` (string, optional): Project description
  518. - `public` (boolean, optional): Whether the project is public
  519. - `status` (string, optional): Project status
  520. - `parent_id` (integer, optional): Parent project ID
  521. **Example:**
  522. ```
  523. Create a new project named "Website Redesign" with identifier "web-redesign"
  524. ```
  525. #### 22. `update_project`
  526. Update an existing project.
  527. **Parameters:**
  528. - `project_id` (integer, required): Project ID
  529. - `name` (string, optional): Project name
  530. - `identifier` (string, optional): Project identifier
  531. - `description` (string, optional): Project description
  532. - `public` (boolean, optional): Whether the project is public
  533. - `status` (string, optional): Project status
  534. - `parent_id` (integer, optional): Parent project ID
  535. #### 23. `delete_project`
  536. Delete a project.
  537. **Parameters:**
  538. - `project_id` (integer, required): Project ID
  539. #### 24. `get_project`
  540. Get detailed information about a specific project.
  541. **Parameters:**
  542. - `project_id` (integer, required): Project ID
  543. #### 25. `create_membership`
  544. Create a new project membership.
  545. **Parameters:**
  546. - `project_id` (integer, required): Project ID
  547. - `user_id` (integer, optional): User ID (required if group_id not provided)
  548. - `group_id` (integer, optional): Group ID (required if user_id not provided)
  549. - `role_ids` (array, optional): Array of role IDs
  550. - `role_id` (integer, optional): Single role ID (alternative to role_ids)
  551. - `notification_message` (string, optional): Optional notification message
  552. **Example:**
  553. ```
  554. Add user 5 to project 2 with role ID 3 (Developer role)
  555. ```
  556. #### 26. `update_membership`
  557. Update an existing membership.
  558. **Parameters:**
  559. - `membership_id` (integer, required): Membership ID
  560. - `role_ids` (array, optional): Array of role IDs
  561. - `role_id` (integer, optional): Single role ID
  562. - `notification_message` (string, optional): Optional notification message
  563. #### 27. `delete_membership`
  564. Delete a membership.
  565. **Parameters:**
  566. - `membership_id` (integer, required): Membership ID
  567. #### 28. `get_membership`
  568. Get detailed information about a specific membership.
  569. **Parameters:**
  570. - `membership_id` (integer, required): Membership ID
  571. #### 29. `list_project_members`
  572. List all members of a specific project.
  573. **Parameters:**
  574. - `project_id` (integer, required): Project ID
  575. **Example:**
  576. ```
  577. List all members of project 5
  578. ```
  579. #### 30. `list_user_projects`
  580. List all projects a specific user is assigned to.
  581. **Parameters:**
  582. - `user_id` (integer, required): User ID
  583. #### 31. `list_roles`
  584. List all available roles.
  585. **Example:**
  586. ```
  587. List all available roles in the OpenProject instance
  588. ```
  589. #### 32. `get_role`
  590. Get detailed information about a specific role.
  591. **Parameters:**
  592. - `role_id` (integer, required): Role ID
  593. #### 33. `set_work_package_parent`
  594. Set a parent for a work package (create parent-child relationship).
  595. **Parameters:**
  596. - `work_package_id` (integer, required): Work package ID to become a child
  597. - `parent_id` (integer, required): Work package ID to become the parent
  598. **Example:**
  599. ```
  600. Set work package 15 as a child of work package 10
  601. ```
  602. #### 34. `remove_work_package_parent`
  603. Remove parent relationship from a work package (make it top-level).
  604. **Parameters:**
  605. - `work_package_id` (integer, required): Work package ID to remove parent from
  606. #### 35. `list_work_package_children`
  607. List all child work packages of a parent.
  608. **Parameters:**
  609. - `parent_id` (integer, required): Parent work package ID
  610. - `include_descendants` (boolean, optional): Include grandchildren and all descendants (default: false)
  611. **Example:**
  612. ```
  613. List all children of work package 10 including descendants
  614. ```
  615. #### 36. `create_work_package_relation`
  616. Create a relationship between work packages.
  617. **Parameters:**
  618. - `from_id` (integer, required): Source work package ID
  619. - `to_id` (integer, required): Target work package ID
  620. - `relation_type` (string, required): Relation type (blocks, follows, precedes, relates, duplicates, includes, requires, partof)
  621. - `lag` (integer, optional): Lag in working days (for follows/precedes)
  622. - `description` (string, optional): Optional description of the relation
  623. **Example:**
  624. ```
  625. Create a "blocks" relation where work package 5 blocks work package 8
  626. ```
  627. #### 37. `list_work_package_relations`
  628. List work package relations with optional filtering.
  629. **Parameters:**
  630. - `work_package_id` (integer, optional): Filter relations involving this work package ID
  631. - `relation_type` (string, optional): Filter by relation type
  632. #### 38. `update_work_package_relation`
  633. Update an existing work package relation.
  634. **Parameters:**
  635. - `relation_id` (integer, required): Relation ID
  636. - `relation_type` (string, optional): New relation type
  637. - `lag` (integer, optional): Lag in working days
  638. - `description` (string, optional): Optional description
  639. #### 39. `delete_work_package_relation`
  640. Delete a work package relation.
  641. **Parameters:**
  642. - `relation_id` (integer, required): Relation ID
  643. #### 40. `get_work_package_relation`
  644. Get detailed information about a specific work package relation.
  645. **Parameters:**
  646. - `relation_id` (integer, required): Relation ID
  647. ## Development
  648. ### Setting up Development Environment
  649. ```bash
  650. # Install development dependencies
  651. uv sync --extra dev
  652. # Or install manually
  653. uv pip install -e ".[dev]"
  654. ```
  655. ### Running Tests
  656. ```bash
  657. uv run pytest tests/
  658. ```
  659. ### Code Formatting
  660. ```bash
  661. # Format code
  662. uv run black openproject-mcp.py
  663. # Lint code
  664. uv run flake8 openproject-mcp.py
  665. ```
  666. ### Adding Dependencies
  667. ```bash
  668. # Add a new dependency
  669. uv add package-name
  670. # Add a development dependency
  671. uv add --dev package-name
  672. # Update dependencies
  673. uv sync
  674. ```
  675. ## Tool Compatibility & Test Results
  676. ### ✅ Fully Working Tools (40/42)
  677. All these tools have been tested and work correctly with admin privileges:
  678. **Core Project Management:**
  679. - `test_connection`, `check_permissions`, `list_projects`, `create_project`, `update_project`
  680. - `delete_project`, `get_project`
  681. **Work Package Management:**
  682. - `list_work_packages`, `search_work_packages`, `list_types`, `create_work_package`, `update_work_package`
  683. - `delete_work_package`, `get_work_package`, `list_statuses`, `list_priorities`
  684. **Work Package Hierarchy & Relations:**
  685. - `set_work_package_parent`, `remove_work_package_parent`, `list_work_package_children`
  686. - `create_work_package_relation`, `list_work_package_relations`, `update_work_package_relation`
  687. - `delete_work_package_relation`, `get_work_package_relation`
  688. **User & Membership Management:**
  689. - `list_users`, `get_user`, `create_membership`, `update_membership`, `delete_membership`
  690. - `get_membership`, `list_project_members`, `list_user_projects`, `list_roles`, `get_role`
  691. **Time Tracking:**
  692. - `list_time_entries`, `create_time_entry`, `update_time_entry`, `delete_time_entry`
  693. **Project Versions:**
  694. - `list_versions`, `create_version`
  695. ### ⚠️ Partially Working Tools
  696. - **`list_memberships`**: Works globally and with `project_id` filtering. User ID filtering (`user_id`) may not be supported in all OpenProject instances.
  697. ### ❌ Endpoint Limitations with Workarounds
  698. - **`list_time_entry_activities`**: Returns 404 but time entry activities ARE functional! Use these predefined activity IDs:
  699. - **Management (ID: 1)**: Administrative and planning tasks
  700. - **Specification (ID: 2)**: Requirements and documentation
  701. - **Development (ID: 3)**: Coding and implementation
  702. - **Testing (ID: 4)**: Quality assurance and testing
  703. **Example**: `create_time_entry` with `activity_id: 3` for Development work
  704. ### Permission Requirements
  705. Most create/update/delete operations require appropriate permissions:
  706. - **Project Operations**: Require global "Create project" and "Edit project" permissions. Deletion typically requires admin rights
  707. - **Work Package Operations**: Require "Create/Edit work packages" permission in target projects
  708. - **Work Package Relations & Hierarchy**: Require "Edit work packages" permission for creating/modifying parent-child relationships and dependencies
  709. - **Membership Management**: Require "Manage members" permission for target projects
  710. - **Time Entry Operations**: Require time tracking permissions
  711. - **Version Management**: Require project admin or version management permissions
  712. - **User Operations**: Admin privileges may be needed for comprehensive user management
  713. - **Role Management**: Read-only operations generally available; admin privileges may be needed for detailed role information
  714. Use the `check_permissions` tool to diagnose permission-related issues.
  715. ## Troubleshooting
  716. ### Connection Issues
  717. 1. **401 Unauthorized**: Check your API key is correct and active
  718. 2. **403 Forbidden**: Ensure your user has the necessary permissions
  719. 3. **404 Not Found**: Verify the OpenProject URL and that resources exist
  720. 4. **Proxy Errors**: Check proxy settings and authentication
  721. ### Debug Mode
  722. Enable debug logging by setting:
  723. ```env
  724. LOG_LEVEL=DEBUG
  725. ```
  726. ### Common Issues
  727. - **No projects found**: Ensure your API user has project view permissions
  728. - **SSL errors**: May occur with self-signed certificates or proxy SSL interception
  729. - **Timeout errors**: Increase timeout or check network connectivity
  730. ## Security Considerations
  731. - Never commit your `.env` file to version control
  732. - Use environment variables for sensitive data
  733. - Rotate API keys regularly
  734. - Use HTTPS for all OpenProject connections
  735. - Configure proxy authentication securely if needed
  736. ## Contributing
  737. 1. Fork the repository
  738. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  739. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  740. 4. Push to the branch (`git push origin feature/amazing-feature`)
  741. 5. Open a Pull Request
  742. ## License
  743. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  744. ## Acknowledgments
  745. - Built for the [Model Context Protocol](https://modelcontextprotocol.io/)
  746. - Integrates with [OpenProject](https://www.openproject.org/)
  747. - Inspired by the MCP community
  748. ## Support
  749. - 🐛 Issues: [GitHub Issues](https://github.com/AndyEverything/openproject-mcp-server/issues)
  750. - 💬 Discussions: [GitHub Discussions](https://github.com/AndyEverything/openproject-mcp-server/discussions)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.