OpenProject MCP Server by GeXDigital

A high-performance Model Context Protocol (MCP) server for OpenProject API v3 integration with AI applications.

Release 1.2.0 • 50 Tools

---

Table of Contents

• Quick Start
• Features
• Documentation
• Configuration
• Integration
• Development
• Contributing
• License
• Support
• Maintainer

---

Quick Start (5 Minutes)

Prerequisites

• Python 3.10 or higher
• uv package manager
• OpenProject instance with API access

Installation

1. Install uv (if needed):

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

2. Clone and setup:

git clone <your-repo-url>
cd gx-op-mcp
uv sync

3. Configure environment:

cp env_example.txt .env

Edit .env with your OpenProject credentials:

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

4. Test connection:

uv run python openproject-mcp.py

✅ Done! Your MCP server is running.

↑ Back to Table of Contents

---

Features

Core Capabilities

• 50 Production-Ready Tools - Complete OpenProject API v3 coverage
• High Performance - Sub-110ms tool discovery, negative execution overhead
• Modular Architecture - Self-registering tools with 96.9% code reduction
• Full CRUD Operations - Projects, work packages, users, roles, memberships

Key Operations

• 📋 Project Management - Hierarchical projects with parent/child relationships
• 📝 Work Packages - Complete lifecycle with time tracking and budgets
• 🔗 Relations - Complex dependencies (blocks, follows, precedes, requires)
• 💬 Comments - Create, read, update with activity history
• ⏱️ Time Tracking - Log hours with activity types
• 👥 Team Management - Users, roles, and project memberships
• 📊 Views & Exports - Query system with Excel export

Technical Features

• 🔐 Secure API key authentication
• 🌐 Proxy support for corporate environments
• 🔒 Configurable SSL verification
• 🚀 Async/await for concurrent operations
• 📊 Comprehensive error handling and logging

↑ Back to Table of Contents

---

Documentation

Getting Started

• Quick Start Guide - Get running in 5 minutes
• Configuration - Environment setup and options
• Integration Guide - Connect with Claude Desktop and other MCP clients

Reference Documentation

• Tools Reference - Complete catalog of all 50 tools organized by category
• Architecture Guide - System design, patterns, and extension guide
• Changelog - Version history and release notes

Migration & Upgrades

• Migration Guide - Upgrading from v1.0.x to v1.1.0

External Resources

• OpenProject API Documentation - Official API reference
• Model Context Protocol - MCP specification

↑ Back to Table of Contents

---

Configuration

Environment Variables

Variable	Required	Description
OPENPROJECT_URL	Yes	Your OpenProject instance URL
OPENPROJECT_API_KEY	Yes	API key from your user profile
OPENPROJECT_PROXY	No	HTTP proxy URL if needed
OPENPROJECT_VERIFY_SSL	No	Verify SSL certificates (default: true)

Getting Your API Key

1. Log in to your OpenProject instance
2. Click your avatar → My account
3. Navigate to Access tokens
4. Click + Add to create a new token
5. Copy the generated token to your .env file

↑ Back to Table of Contents

---

Integration

Claude Desktop

Add to your Claude Desktop config file:

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

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

Replace /path/to/gx-op-mcp/ with your actual installation path.

Other MCP Clients

The server implements the standard MCP protocol and works with any compliant client. See the MCP documentation for integration details.

↑ Back to Table of Contents

---

Development

Setup Development Environment

uv sync --extra dev

Run Tests

uv run pytest tests/

Code Formatting

uv run black openproject-mcp.py
uv run flake8 openproject-mcp.py

Add Dependencies

uv add package-name          # Add runtime dependency
uv add --dev package-name    # Add dev dependency

↑ Back to Table of Contents

---

Contributing

Contributions are welcome! Please follow these steps:

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

↑ Back to Table of Contents

---

License

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

↑ Back to Table of Contents

---

Support

• 🐛 Issues: Report bugs or request features via GitHub Issues
• 📖 Documentation: Check the docs directory for detailed guides
• 💡 Questions: Open a GitHub Discussion

↑ Back to Table of Contents

---

Maintainer

This is a maintained fork of openproject-mcp-server.

Special thanks to @AndyEverything for laying the first brick on this project. We created this fork to contribute and evolve faster while maintaining the original vision.

Maintainer: GeXDigital Networks

↑ Back to Table of Contents

---

Quick Reference

Most Used Tools

# Connection & Setup
test_connection              # Verify API connection
check_permissions           # Check user capabilities

# Projects
list_projects               # List all accessible projects
get_project                 # Get project details
create_project              # Create new project

# Work Packages
list_work_packages          # List work packages with filters
get_work_package            # Get work package details
create_work_package         # Create new work package
update_work_package         # Update work package

# Time Tracking
create_time_entry           # Log time on work package
list_time_entries           # List time entries

# Views & Export
get_view                    # Retrieve saved query
export_view                 # Export view to Excel

See Tools Reference for the complete list of 50 tools.

---

Copyright (c) 2026 GeXDigital Networks and Contributors Licensed under the MIT License.

Made with ❤️ by the Community and GeXDigital Networks.