# OpenProject MCP Server
A Model Context Protocol (MCP) server for OpenProject API v3 integration. This server provides comprehensive tools for managing work packages, comments, projects, and relations in OpenProject through Claude Desktop and other MCP clients.
## Features
- **Work Package Management** (10 tools)
- Create, read, update, delete work packages
- Manage assignees and watchers
- Set parent-child relationships
- Get work package schema
- **Comment & Activity Management** (4 tools)
- Get work package activities
- Create and update comments
- View activity details
- **Project Management** (3 tools)
- Get project details
- List projects with filtering
- Update project properties
- **Relation Management** (4 tools)
- List work package relations
- Create relations (relates, blocks, precedes, etc.)
- Delete relations
## Installation
### Prerequisites
- Python 3.11 or higher
- [uv](https://docs.astral.sh/uv/) package manager
- OpenProject account with API access
### Setup
1. Clone the repository:
```bash
git clone <your-repo-url>
cd openproject-mcp
```
2. Install dependencies:
```bash
uv sync
```
3. Create a `.env` file (copy from `.env.example`):
```bash
cp .env.example .env
```
4. Configure your OpenProject credentials in `.env`:
```bash
OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_KEY=your_api_key_here
```
### Getting Your API Key
1. Log in to your OpenProject instance
2. Go to **My Account** (top-right menu)
3. Select **Access tokens** from the left sidebar
4. Click **+ API** to generate a new API key
5. Copy the key and paste it into your `.env` file
## Docker Installation (Alternative)
You can also run the server using Docker:
### Using Docker Compose (Recommended)
1. Create a `.env` file with your credentials:
```bash
cp .env.example .env
# Edit .env with your OpenProject URL and API key
```
2. Build and run with Docker Compose:
```bash
docker-compose up -d
```
3. View logs:
```bash
docker-compose logs -f
```
4. Stop the server:
```bash
docker-compose down
```
### Using Docker directly
1. Build the Docker image:
```bash
docker build -t openproject-mcp .
```
2. Run the container:
```bash
docker run -it --rm \
-e OPENPROJECT_URL=https://your-instance.openproject.com \
-e OPENPROJECT_API_KEY=your_api_key_here \
openproject-mcp
```
### Using with Claude Desktop (Docker)
To use the Docker container with Claude Desktop, update your configuration:
```json
{
"mcpServers": {
"openproject": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"OPENPROJECT_URL=https://your-instance.openproject.com",
"-e",
"OPENPROJECT_API_KEY=your_api_key_here",
"openproject-mcp"
]
}
}
}
```
## Usage with Claude Desktop
### Configuration
Add the server to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"openproject": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/openproject-mcp",
"run",
"openproject-mcp"
],
"env": {
"OPENPROJECT_URL": "https://your-instance.openproject.com",
"OPENPROJECT_API_KEY": "your_api_key_here"
}
}
}
}
```
Replace `/absolute/path/to/openproject-mcp` with the actual path to this project directory.
### Restart Claude Desktop
After updating the configuration, restart Claude Desktop to load the server.
## Example Usage
### Work Packages
**Create a work package:**
```
Create a new task in project "demo-project" with subject "Fix login bug" and description "Users cannot log in with special characters in password"
```
**Get work package details:**
```
Get details for work package #123
```
*Note: Work package details are returned as formatted markdown with all key information including status, type, priority, project, hierarchy, costs, and description.*
**Update a work package:**
```
Update work package #123: change status to "In Progress" and assign to user 5
```
**List work packages:**
```
List all work packages in project "demo-project"
```
*Note: Work packages are displayed as a formatted list showing ID, subject, type, status, priority, project, assignee, due date, and parent (if any).*
**Set parent work package:**
```
Set work package #456 as the parent of work package #123
```
### Comments
**Add a comment:**
```
Add a comment to work package #123: "I've started working on this issue"
```
**Get activities:**
```
Show me all activities and comments for work package #123
```
*Note: Activities are returned as formatted markdown with user, timestamp, comments, and change details for easy reading.*
### Projects
**Get project details:**
```
Get details for project "demo-project"
```
**List projects:**
```
List all active projects
```
**Update project:**
```
Update project "demo-project": change description to "Demo project for testing"
```
### Relations
**Create a relation:**
```
Create a "blocks" relation from work package #123 to work package #456
```
**List relations:**
```
Show all relations for work package #123
```
## Available Tools
### Work Package Tools
1. **create_work_package** - Create a new work package
2. **get_work_package** - Get work package details (formatted as markdown)
3. **update_work_package** - Update work package fields
4. **list_work_packages** - List work packages with filtering (formatted as markdown)
5. **delete_work_package** - Delete a work package
6. **get_available_assignees** - Get assignable users for a project
7. **add_watcher** - Add a watcher to a work package
8. **remove_watcher** - Remove a watcher
9. **get_work_package_schema** - Get schema for work package creation
10. **set_parent_work_package** - Set or remove the parent of a work package
### Comment Tools
1. **get_work_package_activities** - Get all activities/comments (formatted as markdown)
2. **create_comment** - Add a comment to a work package
3. **get_activity** - Get specific activity details
4. **update_comment** - Update an existing comment
### Project Tools
1. **get_project** - Get project details
2. **list_projects** - List all accessible projects
3. **update_project** - Update project properties
### Relation Tools
1. **list_work_package_relations** - Get all relations for a work package
2. **create_relation** - Create a relation between work packages
3. **get_relation** - Get specific relation details
4. **delete_relation** - Delete a relation
## Relation Types
When creating relations, you can use the following types:
- `relates` - General relation
- `duplicates` - Source duplicates target
- `duplicated` - Source is duplicated by target
- `blocks` - Source blocks target
- `blocked` - Source is blocked by target
- `precedes` - Source precedes target (supports lag in days)
- `follows` - Source follows target (supports lag in days)
- `includes` - Source includes target (parent-child)
- `partof` - Source is part of target (child-parent)
- `requires` - Source requires target
- `required` - Source is required by target
## Development
### Running Tests
```bash
uv run pytest
```
### Code Formatting
```bash
uv run black src/
```
### Type Checking
```bash
uv run mypy src/
```
### Linting
```bash
uv run ruff check src/
```
## Architecture
The server is built with:
- **FastMCP** - Official MCP Python SDK for tool definition
- **httpx** - Async HTTP client for OpenProject API calls
- **Pydantic** - Configuration and data validation
- **python-dotenv** - Environment variable management
### Project Structure
```
openproject-mcp/
├── src/openproject_mcp/
│ ├── server.py # Main MCP server
│ ├── client.py # OpenProject API client
│ ├── config.py # Configuration management
│ ├── tools/
│ │ ├── work_packages.py # Work package tools
│ │ ├── comments.py # Comment tools
│ │ ├── projects.py # Project tools
│ │ └── relations.py # Relation tools
│ └── utils/
│ ├── errors.py # Custom exceptions
│ └── hal.py # HAL+JSON helpers
├── tests/ # Test files
├── pyproject.toml # Dependencies
├── .env.example # Example environment variables
└── README.md # This file
```
## Authentication
The server uses API key authentication with OpenProject. The API key is encoded as Basic Auth:
```
Authorization: Basic base64(apikey:<your_api_key>)
```
All requests are made to the OpenProject API v3 endpoint (`/api/v3/`).
## Error Handling
The server includes comprehensive error handling for common scenarios:
- **401 Unauthorized** - Invalid API key
- **403 Forbidden** - Insufficient permissions
- **404 Not Found** - Resource doesn't exist
- **409 Conflict** - Lock version mismatch (fetch latest and retry)
- **422 Unprocessable Entity** - Validation errors
- **429 Too Many Requests** - Rate limit exceeded
## Lock Versions
OpenProject uses optimistic locking to prevent concurrent modifications. When updating resources (work packages, projects, comments), you must provide the current `lockVersion`:
1. Fetch the resource to get the current `lockVersion`
2. Make your changes
3. Send the update with the `lockVersion`
4. If you get a 409 Conflict, fetch the resource again and retry
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
[Your License Here]
## Support
For issues and questions:
- OpenProject API Documentation: https://www.openproject.org/docs/api/
- MCP Documentation: https://modelcontextprotocol.io/
## Acknowledgments
Built with the [Model Context Protocol](https://modelcontextprotocol.io/) and [OpenProject API v3](https://www.openproject.org/docs/api/).
