⚠️ This is an early-stage project. Do not use it productively – contributions welcome!

OpenProject MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with OpenProject API v3. This server enables LLM applications to interact with OpenProject for project management, work package tracking, and task creation.

Features

• 🔌 Full OpenProject API v3 Integration
• 📋 Project Management: List and filter projects
• 📝 Work Package Management: Create, list, and filter work packages
• 🏷️ Type Management: List available work package types
• 🔐 Secure Authentication: API key-based authentication
• 🌐 Proxy Support: Optional HTTP proxy configuration
• 🚀 Async Operations: Built with modern async/await patterns
• 📊 Comprehensive Logging: Configurable logging levels

Prerequisites

• Python 3.8 or higher
• An OpenProject instance (cloud or self-hosted)
• OpenProject API key (generated from your user profile)

Installation

1. Clone the repository:

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

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Copy the environment template:

cp .env.example .env

5. Edit .env and add your OpenProject configuration:

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

Configuration

Environment Variables

Variable	Required	Description	Example
OPENPROJECT_URL	Yes	Your OpenProject instance URL	https://mycompany.openproject.com
OPENPROJECT_API_KEY	Yes	API key from your OpenProject user profile	8169846b42461e6e...
OPENPROJECT_PROXY	No	HTTP proxy URL if needed	http://proxy.company.com:8080
LOG_LEVEL	No	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
TEST_CONNECTION_ON_STARTUP	No	Test API connection when server starts	true

Getting an API Key

1. Log in to your OpenProject instance
2. Go to My account (click your avatar)
3. Navigate to Access tokens
4. Click + Add to create a new token
5. Give it a name and copy the generated token

Usage

Running the Server

python openproject-mcp.py

Note: If you renamed the file from openproject_mcp_server.py, update your configuration accordingly.

Integration with Claude Desktop

Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openproject": {
      "command": "python",
      "args": ["path/to/openproject-mcp.py"]
    }
  }
}

Available Tools

1. test_connection

Test the connection to your OpenProject instance.

Example:

Test the OpenProject connection

2. list_projects

List all projects you have access to.

Parameters:

• active_only (boolean, optional): Show only active projects (default: true)

Example:

List all active projects

3. list_work_packages

List work packages with optional filtering.

Parameters:

• project_id (integer, optional): Filter by specific project
• status (string, optional): Filter by status - "open", "closed", or "all" (default: "open")

Example:

Show all open work packages in project 5

4. list_types

List available work package types.

Parameters:

• project_id (integer, optional): Filter types by project

Example:

List all work package types

5. create_work_package

Create a new work package.

Parameters:

• project_id (integer, required): The project ID
• subject (string, required): Work package title
• type_id (integer, required): Type ID (e.g., 1 for Task)
• description (string, optional): Description in Markdown format
• priority_id (integer, optional): Priority ID
• assignee_id (integer, optional): User ID to assign to

Example:

Create a new task in project 5 titled "Update documentation" with type ID 1

Development

Running Tests

pytest tests/

Code Formatting

black openproject-mcp.py
flake8 openproject-mcp.py

Troubleshooting

Connection Issues

1. 401 Unauthorized: Check your API key is correct and active
2. 403 Forbidden: Ensure your user has the necessary permissions
3. 404 Not Found: Verify the OpenProject URL and that resources exist
4. Proxy Errors: Check proxy settings and authentication

Debug Mode

Enable debug logging by setting:

LOG_LEVEL=DEBUG

Common Issues

• No projects found: Ensure your API user has project view permissions
• SSL errors: May occur with self-signed certificates or proxy SSL interception
• Timeout errors: Increase timeout or check network connectivity

Security Considerations

• Never commit your .env file to version control
• Use environment variables for sensitive data
• Rotate API keys regularly
• Use HTTPS for all OpenProject connections
• Configure proxy authentication securely if needed

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for the Model Context Protocol
• Integrates with OpenProject
• Inspired by the MCP community

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions