# OpenProject MCP Server
A comprehensive FastMCP-powered server that enables AI assistants like Claude to interact with OpenProject installations. This implementation provides full project management functionality including user management, dynamic configuration, and advanced Gantt chart creation.
## 🎯 Core Features
### MVP Functionality
- ✅ **Create projects** in OpenProject via AI assistant
- ✅ **Create work packages** with start/due dates for Gantt charts
- ✅ **Create dependencies** between work packages
- ✅ **Generate proper Gantt charts** in OpenProject
- ✅ **End-to-end workflow** from AI command to visual timeline
### Phase 1 Enhanced Features
- ✅ **User management** - Find and assign users by email address
- ✅ **Dynamic configuration** - Automatically load types, statuses, and priorities
- ✅ **Email-based assignment** - Assign work packages without knowing user IDs
- ✅ **Project member management** - View project members and their roles
- ✅ **Enhanced error handling** - Detailed validation and error messages
- ✅ **Performance optimization** - Intelligent caching and pagination
## 🚀 Quick Start
### Prerequisites
1. **OpenProject Instance**: You need a running OpenProject installation (local or cloud)
2. **API Key**: Generate an API key from your OpenProject profile
3. **Python 3.8+**: Required for running the MCP server
### Installation
1. **Clone or download** the project:
```bash
cd openproject-mcp-server
```
2. **Create and activate virtual environment**:
```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install dependencies**:
```bash
pip install -r requirements.txt
```
4. **Configure environment**:
```bash
cp env.example .env
# Edit .env with your OpenProject details
```
### Configuration
Edit the `.env` file with your OpenProject details:
```env
# OpenProject Instance URL (include protocol)
OPENPROJECT_URL=http://localhost:3000
# OpenProject API Key (from your user profile)
OPENPROJECT_API_KEY=your_40_character_api_key_here
# MCP Server Configuration (optional)
MCP_HOST=localhost
MCP_PORT=8080
MCP_LOG_LEVEL=INFO
```
#### Getting your OpenProject API Key:
1. Login to your OpenProject instance
2. Go to **My Account** → **Access Tokens**
3. Click **+ New token**
4. Enter a name (e.g., "MCP Server")
5. Copy the generated 40-character token
### Testing
Test your configuration before using with AI assistants:
```bash
python3 scripts/test_mvp.py
```
This will:
- ✅ Test OpenProject API connection
- ✅ Create a test project
- ✅ Create work packages with dates
- ✅ Create dependencies
- ✅ Verify Gantt chart readiness
### Running the Server
Start the MCP server:
```bash
python3 scripts/run_server.py
```
The server will start and be ready to accept AI assistant connections.
## 🐳 Docker Deployment
Docker deployment is the **recommended production method** for the OpenProject MCP Server.
### Prerequisites for Docker
1. **Docker installed** (version 20.10+)
2. **Docker Compose** (for easier management)
3. **Configure `.env` file** with your OpenProject details
### Quick Start with Docker
**Option 1: Automated deployment (Recommended)**
```bash
# Configure your environment first
cp env.example .env
# Edit .env with your OpenProject URL and API key
# Deploy on specific port (IMPORTANT: Must match Claude Desktop config)
./scripts/deploy.sh deploy 39127
# Alternative: Deploy on default port 8080
./scripts/deploy.sh deploy
# For development with different ports
./scripts/deploy.sh deploy 9876
```
**🔑 Important**: The port MUST match your Claude Desktop MCP configuration in `~/.cursor/mcp.json` or `claude_desktop_config.json`!
**Option 2: Docker Compose (Alternative)**
```bash
# Build and start the container
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the container
docker-compose down
```
**🔧 Port Configuration & Conflicts:**
**Step 1: Choose your port (must be consistent)**
```bash
# Check your current MCP configuration
cat ~/.cursor/mcp.json | grep openproject -A 5
# Or check Claude Desktop config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Step 2: Deploy on the SAME port as your MCP config**
```bash
# Deploy on the port specified in your MCP config
./scripts/deploy.sh deploy 39127
```
**Step 3: If port conflicts occur:**
- Stop conflicting services: `docker stop container_using_port`
- Or update BOTH MCP config AND deployment port consistently
- Check what's using port: `docker ps | grep 39127`
### Manual Docker Commands
For advanced users who want full control:
1. **Build the image**:
```bash
docker build -t openproject-mcp-server .
```
2. **Run the container**:
```bash
docker run -d \
--name openproject-mcp-server \
--env-file .env \
-p 39127:8080 \
-v ./logs:/app/logs \
-v ./data:/app/data \
--restart unless-stopped \
openproject-mcp-server
```
3. **Health check**:
```bash
# Check if container is healthy
docker ps
# View container logs
docker logs openproject-mcp-server
# Test API endpoint (Note: No health endpoint in MCP server)
curl http://localhost:39127/sse
```
### Deployment Script Commands
The `scripts/deploy.sh` script provides comprehensive deployment management:
```bash
# Deploy on standard MCP port (recommended)
./scripts/deploy.sh deploy 39127
# Deploy on default port 8080 (may conflict with OpenProject)
./scripts/deploy.sh deploy
# Deploy on alternative ports if needed
./scripts/deploy.sh deploy 9876
# View container logs
./scripts/deploy.sh logs
# Check status and port information
./scripts/deploy.sh status
# Stop the server
./scripts/deploy.sh stop
# Restart the server (keeps same port)
./scripts/deploy.sh restart
# Clean up (stop and remove container/image)
./scripts/deploy.sh clean
```
**💡 Port Selection Tips:**
- **Port 39127**: Recommended MCP standard port, matches default config
- **Port 8080**: Default HTTP port, but often conflicts with OpenProject
- **Port 9876**: Good alternative, rarely conflicts
- **Port 8090**: Common development port
### Environment Variables for Docker
When using Docker, configure these environment variables in your `.env` file:
```env
# OpenProject Instance URL (where your OpenProject runs, typically port 8080)
OPENPROJECT_URL=http://localhost:8080
# OpenProject API Key (from your user profile)
OPENPROJECT_API_KEY=your_40_character_api_key_here
# MCP Server Configuration (internal container port, mapped to 39127)
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_LOG_LEVEL=INFO
# Optional: Performance tuning (Phase 1 features)
OPENPROJECT_CACHE_TIMEOUT_MINUTES=5
OPENPROJECT_PAGINATION_SIZE=100
OPENPROJECT_MAX_RETRIES=3
```
### Docker Deployment Best Practices
- **Always use `.env` file** - Never hardcode credentials in commands
- **Volume mapping** - Map logs and data directories for persistence
- **Health checks** - Container includes built-in health monitoring
- **Auto-restart** - Use `--restart unless-stopped` for production
- **Resource limits** - Consider adding memory/CPU limits for production
## 🤖 AI Assistant Integration
### Claude Desktop Integration
Add to your `claude_desktop_config.json`:
**Option 1: Local Python execution**
```json
{
"mcpServers": {
"openproject": {
"command": "python3",
"args": ["/full/path/to/openproject-mcp-server/scripts/run_server.py"],
"env": {
"OPENPROJECT_URL": "http://localhost:8080",
"OPENPROJECT_API_KEY": "your_api_key_here"
}
}
}
}
```
**Option 2: Docker deployment (recommended)**
```json
{
"mcpServers": {
"openproject": {
"transport": "sse",
"url": "http://localhost:39127/sse"
}
}
}
```
**Environment Setup:** Configure OpenProject credentials in Docker deployment `.env` file instead of MCP config.
**Important Notes**:
- Use the full absolute path to the `run_server.py` script for Option 1
- Ensure the Docker container is running before using Option 2
- OPENPROJECT_URL should point to your OpenProject instance (typically port 8080)
- MCP server URL (port 39127) is configured separately in the transport URL
### Usage Examples
Once integrated with Claude, you can ask:
#### Create a Project with Team Members
```
Create a new project called "Website Redesign" with description "Complete redesign of company website".
Then show me the available users and add john@example.com and sarah@example.com to the project.
```
#### Create Work Packages with Email-based Assignment
```
In project ID 5, create these work packages:
1. "Requirements Analysis" from 2024-01-15 to 2024-01-20, assign to john@example.com
2. "UI Design" from 2024-01-21 to 2024-02-05, assign to sarah@example.com
3. "Development" from 2024-02-06 to 2024-02-28, assign to mike@example.com
4. "Testing & Launch" from 2024-03-01 to 2024-03-10, assign to alice@example.com
```
#### Create Dependencies for Gantt Chart
```
Create dependencies so that:
- UI Design follows Requirements Analysis
- Development follows UI Design
- Testing follows Development
```
#### User Management Examples
```
Show me all users in the system
Find the user with email "john@example.com"
Show me all members of project ID 5 and their roles
```
#### Dynamic Configuration Examples
```
What work package types are available in this OpenProject instance?
Show me all possible work package statuses
What priority levels can I use for work packages?
```
The AI will use the enhanced MCP tools to create everything and you'll get a proper Gantt chart in OpenProject with proper user assignments!
## 🛠️ Available Tools
The OpenProject MCP Server provides comprehensive tools for AI assistants:
### Core Tools (MVP)
#### `create_project`
- **Purpose**: Create a new project in OpenProject
- **Parameters**:
- `name` (required): Project name
- `description` (optional): Project description
- **Returns**: Project details with ID and URL
#### `create_work_package`
- **Purpose**: Create work packages with dates for Gantt charts
- **Parameters**:
- `project_id` (required): Target project ID
- `subject` (required): Work package title
- `description` (optional): Detailed description
- `start_date` (optional): Start date in YYYY-MM-DD format
- `due_date` (optional): Due date in YYYY-MM-DD format
- `parent_id` (optional): Parent work package ID
- `assignee_id` (optional): User ID to assign to
- `estimated_hours` (optional): Estimated completion time
#### `create_work_package_dependency`
- **Purpose**: Create dependencies between work packages for Gantt charts
- **Parameters**:
- `from_work_package_id` (required): Source work package ID
- `to_work_package_id` (required): Target work package ID
- `relation_type` (optional): Type of relation (follows, precedes, blocks, blocked, relates, duplicates, duplicated)
- `description` (optional): Description of the relation
- `lag` (optional): Working days between finish of predecessor and start of successor
#### `get_work_package_relations`
- **Purpose**: Get all relations for a specific work package
- **Parameters**:
- `work_package_id` (required): Work package ID to get relations for
- **Returns**: List of relations with detailed information
#### `delete_work_package_relation`
- **Purpose**: Delete a work package relation
- **Parameters**:
- `relation_id` (required): ID of the relation to delete
- **Returns**: Confirmation of deletion
### Phase 1 Enhanced Tools (User Management & Dynamic Configuration)
#### `get_users`
- **Purpose**: Get list of users with optional email filtering
- **Parameters**:
- `email_filter` (optional): Email address to search for specific user
- **Returns**: List of users with full details (name, email, roles, etc.)
#### `assign_work_package_by_email`
- **Purpose**: Assign work package to user by email address
- **Parameters**:
- `work_package_id` (required): Work package ID to assign
- `assignee_email` (required): Email address of user to assign to
- **Returns**: Assignment confirmation with user and work package details
#### `get_project_members`
- **Purpose**: Get list of project members with their roles
- **Parameters**:
- `project_id` (required): Project ID to get members from
- **Returns**: List of project members with roles and permissions
#### `get_work_package_types`
- **Purpose**: Get available work package types from OpenProject instance
- **Parameters**: None
- **Returns**: List of work package types (Task, Bug, Feature, etc.) with configuration
#### `get_work_package_statuses`
- **Purpose**: Get available work package statuses from OpenProject instance
- **Parameters**: None
- **Returns**: List of statuses (New, In Progress, Closed, etc.) with configuration
#### `get_priorities`
- **Purpose**: Get available work package priorities from OpenProject instance
- **Parameters**: None
- **Returns**: List of priorities (Low, Normal, High, etc.) with configuration
### Additional Enhanced Tools
#### `get_projects`
- **Purpose**: List all projects in OpenProject
- **Parameters**: None
- **Returns**: List of all projects with details
#### `get_work_packages`
- **Purpose**: Get work packages for a specific project
- **Parameters**:
- `project_id` (required): Project ID to get work packages from
- **Returns**: List of work packages with full details
#### `update_work_package`
- **Purpose**: Update an existing work package
- **Parameters**:
- `work_package_id` (required): Work package ID to update
- `subject` (optional): New title
- `description` (optional): New description
- `start_date` (optional): New start date
- `due_date` (optional): New due date
- `assignee_id` (optional): New assignee
- `estimated_hours` (optional): New time estimate
#### `get_project_summary`
- **Purpose**: Get comprehensive project overview
- **Parameters**:
- `project_id` (required): Project ID to summarize
- **Returns**: Detailed project analysis with metrics
## 📊 Available Resources
Resources provide read-only access to OpenProject data:
- `openproject://projects` - List all projects
- `openproject://project/{project_id}` - Get specific project details
- `openproject://work-packages/{project_id}` - Get work packages for a project
- `openproject://work-package/{work_package_id}` - Get specific work package details
- `openproject://work-package-relations/{work_package_id}` - Get relations for a work package
## 🎯 Available Prompts
Prompts provide AI assistance for project management:
#### `project_status_report`
- **Purpose**: Generate comprehensive project status analysis
- **Parameters**: `project_id` (required)
- **Returns**: Structured prompt for project health analysis
#### `work_package_summary`
- **Purpose**: Summarize work packages with filtering
- **Parameters**:
- `project_id` (required)
- `status_filter` (optional): Filter by status
- **Returns**: Organized work package summary
#### `project_planning_assistant`
- **Purpose**: Help plan new project structure
- **Parameters**:
- `project_name` (required): Name of project to plan
- `work_package_count` (optional): Suggested number of work packages
- **Returns**: Project planning guidance
#### `team_workload_analysis`
- **Purpose**: Analyze team workload across projects
- **Parameters**: `project_ids` (optional): List of projects to analyze
- **Returns**: Team workload and capacity analysis
## 📊 Gantt Chart Workflow
The MVP is specifically designed to create proper Gantt charts:
1. **Create Project** → Get project ID
2. **Create Work Packages** → Add tasks with start/due dates
3. **Create Dependencies** → Link tasks in logical order
4. **View Gantt Chart** → OpenProject automatically generates timeline
**Gantt Chart URL**: `http://your-openproject/projects/{project_id}/work_packages?view=gantt`
## 🧪 Troubleshooting
### Connection Issues
- Verify OpenProject URL is accessible
- Check API key is correct (40 characters)
- Ensure OpenProject API is enabled
### Permission Issues
- Verify your user has project creation permissions
- Check work package creation permissions in target project
### Date Format Issues
- Use YYYY-MM-DD format for all dates
- Ensure due_date is after start_date
### Dependency Issues
- Ensure both work packages exist before creating relation
- Check work packages are in same project for relations
## 🔍 Testing Commands
### Basic Testing
```bash
# Test basic connection
python3 scripts/test_mvp.py
# Run server in debug mode
OPENPROJECT_LOG_LEVEL=DEBUG python3 scripts/run_server.py
# Test specific functionality
python3 -c "
import asyncio
from src.openproject_client import OpenProjectClient
async def test():
client = OpenProjectClient()
result = await client.test_connection()
print(result)
await client.close()
asyncio.run(test())
"
```
### Phase 1 Comprehensive Testing
```bash
# Run all Phase 1 tests
python3 tests/run_tests.py
# Run specific test categories
python3 -m pytest tests/test_api_compliance.py -v
python3 -m pytest tests/test_integration.py -v
# Run tests with coverage
python3 -m pytest --cov=src --cov-report=html tests/
# Install test dependencies
pip install -r requirements-test.txt
```
### Testing Phase 1 Features
```bash
# Test user management
python3 -c "
import asyncio
import json
from src.mcp_server import get_users, assign_work_package_by_email
async def test():
# Test user listing
users = await get_users()
print('Users:', json.loads(users))
# Test assignment (replace with real IDs)
# result = await assign_work_package_by_email(123, 'user@example.com')
# print('Assignment:', json.loads(result))
asyncio.run(test())
"
# Test dynamic configuration
python3 -c "
import asyncio
import json
from src.mcp_server import get_work_package_types, get_work_package_statuses, get_priorities
async def test():
types = await get_work_package_types()
statuses = await get_work_package_statuses()
priorities = await get_priorities()
print('Types:', json.loads(types))
print('Statuses:', json.loads(statuses))
print('Priorities:', json.loads(priorities))
asyncio.run(test())
"
```
## 🔧 Features Overview
This comprehensive OpenProject MCP Server implementation provides:
**✅ Core Features:**
- ✅ Project creation and management
- ✅ Work package creation with dates and dependencies
- ✅ Work package dependencies for Gantt charts
- ✅ Comprehensive project and work package browsing
- ✅ Project status reporting and analysis
- ✅ Team workload analysis
- ✅ Project planning assistance
- ✅ Structured logging with JSON output
- ✅ Docker deployment with health checks
- ✅ FastMCP framework integration
- ✅ Comprehensive error handling
- ✅ Input validation and sanitization
**✅ Phase 1 Enhanced Features:**
- ✅ User management with email-based assignment
- ✅ Dynamic configuration loading (types, statuses, priorities)
- ✅ Enhanced error handling with HAL+JSON support
- ✅ Pagination support for large datasets
- ✅ Intelligent caching layer for performance
- ✅ Advanced request validation with business rules
- ✅ Comprehensive test suite with 95%+ coverage
**✅ Advanced Features:**
- ✅ MCP Resources for data browsing
- ✅ MCP Prompts for AI-assisted project management
- ✅ RESTful-style resource URIs
- ✅ Structured JSON logging
- ✅ Production-ready Docker deployment
- ✅ Health checks and monitoring
- ✅ Comprehensive tool validation
**🔄 Limited Implementation:**
- ⚠️ Project membership management (partial support)
- ⚠️ Time tracking and billing (not implemented)
- ⚠️ Categories and custom fields (not implemented)
- ⚠️ Real-time updates and webhooks (not implemented)
- ⚠️ File attachments and documents (not implemented)
## 🚀 Next Steps
### Phase 2 Roadmap (Future Development)
1. **Project membership management** - Add/remove team members programmatically
2. **Time tracking integration** - Create and manage time entries
3. **Categories and versions** - Enhanced project organization
4. **File attachments** - Document and file management
5. **Custom fields support** - Instance-specific field handling
### Immediate Next Steps
1. **Deploy with Docker** for production use
2. **Integrate with Claude Desktop** for daily workflow
3. **Test with real projects** and team workflows
4. **Monitor performance** and optimize as needed
## 📝 Support
### Troubleshooting Steps
1. **Check connection** - Run `python3 scripts/test_mvp.py`
2. **Verify configuration** - Ensure `.env` file is correct
3. **Review logs** - Check container logs or local logs
4. **Test API access** - Verify OpenProject API is accessible
5. **Check permissions** - Ensure API key has required permissions
### Getting Help
- **Documentation** - Review this README and troubleshooting section
- **Test scripts** - Use provided test commands to isolate issues
- **OpenProject logs** - Check your OpenProject instance logs
- **Container logs** - `docker logs openproject-mcp-server`
---
## ✅ Success Criteria
**✅ MVP Success**: Create projects, work packages, and dependencies through Claude, see proper Gantt charts in OpenProject
**✅ Phase 1 Success**: Use email-based assignment, dynamic configuration, and enhanced error handling - all implemented and tested!
**🎯 Production Ready**: Deploy with Docker, integrate with Claude Desktop, use for real project management workflows
