Tonle OpenProject MCP Server

A Model Context Protocol Server for OpenProject - Open Source Project Management Software

Project Overview

Vision Statement

The OpenProject MCP Server is a comprehensive Model Context Protocol (MCP) server that provides seamless integration between AI assistants (such as Claude, Cursor, Windsurf, and other MCP-compatible clients) and OpenProject, the leading open-source project management software. This server enables AI agents to perform the full spectrum of project management operations through OpenProject's API v3, making it possible to automate, query, and manage all aspects of project management through natural language interactions.

What is OpenProject?

OpenProject is an open-source project management software supporting classic, agile, and hybrid project management methodologies. It provides:

• Task Management: Work packages with customizable types, statuses, and workflows

• Gantt Charts: Visual project timelines and scheduling

• Boards: Kanban-style boards for agile workflows

• Team Collaboration: User management, memberships, and notifications

• Time & Cost Reporting: Time tracking and budget management

• Document Management: Wiki pages, attachments, and file storage integrations

• Repository Integration: Version control and revision tracking

What is MCP (Model Context Protocol)?

The Model Context Protocol, developed by Anthropic, is an open standard that enables AI applications to connect to external data sources and tools in a standardized way. MCP provides:

• Standardized Communication: JSON-RPC 2.0 based protocol for consistent interactions

• Universal Compatibility: One integration works with any MCP-compatible AI client

• Three Core Primitives: Tools (actions), Resources (data), and Prompts (templates)

• Secure Data Access: Controlled, authenticated access to external systems

Project Goals

Primary Objectives

1. Complete API Coverage: Implement tools for every OpenProject API v3 endpoint, ensuring no functionality is left inaccessible

2. Intuitive Tool Design: Create well-named, well-documented tools that AI agents can effectively discover and use

3. Production-Ready Quality: Build a robust, secure, and performant server suitable for enterprise deployment

4. Extensibility: Design an architecture that can easily accommodate future OpenProject API expansions

Target Users

• Development Teams: Automate project management tasks through AI-assisted workflows

• Project Managers: Query project status, generate reports, and manage resources via natural language

• DevOps Engineers: Integrate project management into CI/CD pipelines and automation scripts

• Enterprise Organizations: Enable AI-driven project management at scale

Technical Architecture

Technology Stack

To install dependencies:

To run:

Core Technologies

Transport Options

The server supports multiple transport mechanisms:

1. Stdio Transport: For local development and Claude Desktop integration

2. Streamable HTTP Transport: For remote deployments and web-based clients

3. SSE (Server-Sent Events): For real-time notifications and streaming responses

OpenProject API v3 - Complete Endpoint Coverage

API Fundamentals

The OpenProject API v3 is a hypermedia REST API using HAL+JSON format. Key characteristics:

• Base URL: /api/v3/

• Authentication: OAuth2, Session-based, or Basic Auth (API key)

• Response Format: HAL+JSON with embedded resources and links

• Pagination: Offset-based with configurable page size (max 1000)

• Filtering: JSON-based filter expressions

• Sorting: JSON-based sort criteria

Complete Endpoint Categories

The MCP server implements tools for all OpenProject API v3 endpoints organized into the following categories:

1. Work Packages (Core Project Tasks)

Work packages are the fundamental unit of work in OpenProject, representing tasks, features, bugs, milestones, and other work items.

Supported Work Package Properties:

• Subject, description, type, status, priority

• Assignee, responsible, author

• Start date, due date, estimated time, remaining time

• Percentage done, spent time

• Parent work package, children

• Project, version, category

• Custom fields (customFieldN)

• Attachments, relations, watchers

2. Projects

Projects are containers that organize work packages, members, and other resources.

Supported Project Properties:

• Name, identifier, description

• Public/private visibility

• Active status

• Parent project

• Status (on_track, at_risk, off_track)

• Status explanation

• Custom fields

3. Users & Authentication

User Properties:

• Login, email, first name, last name

• Admin status

• Status (active, registered, locked, invited)

• Avatar, language preference

• Identity URL (for SSO)

4. Groups

5. Principals (Users, Groups, Placeholder Users)

6. Memberships

Membership Features:

• Custom notification messages on create/update

• Multiple role assignment

• Project-specific permissions

7. Roles

8. Time Entries

9. Time Entry Activities

10. Activities (Journal Entries)

Activity Features:

• Internal/external visibility

• Attachments on comments

• Emoji reactions

11. Attachments

Attachment Features:

• Multipart upload with metadata

• Containerless attachments (upload then claim)

• Download location links

• Content type and file size information

12. Versions (Releases/Milestones)

Version Properties:

• Name, description, status

• Start date, end date

• Sharing scope (none, descendants, hierarchy, tree, system)

• Custom fields

13. Categories

14. Types (Work Package Types)

Type Properties:

• Name, color, position

• Is default, is milestone

• Attribute groups and visibility

15. Statuses (Work Package Statuses)

Status Properties:

• Name, color, position

• Is closed, is default, is readonly

16. Priorities

17. Relations

Relation Types:

• relates, duplicates, duplicated, blocks, blocked

• precedes, follows, includes, partof, requires, required

18. Queries (Saved Filters)

19. Query Filters, Columns, Operators, Sort Bys

20. Views

21. Notifications

Notification Reasons:

• mentioned, assigned, responsible, watched

• dateAlert, commented, created, scheduled

22. News

23. Posts (Forum Messages)

24. Wiki Pages

25. Documents

26. Budgets

27. Revisions (Repository Commits)

28. File Links & Storages (External File Integration)

Supported Storage Types:

• Nextcloud

• OneDrive/SharePoint

29. Grids (Dashboard Layouts)

Grid Widgets:

• time_entries_current_user

• news, documents

• work_packages_table

• and more...

30. Work Schedule (Days & Non-Working Days)

31. Actions & Capabilities

32. Custom Actions

33. Custom Options (Custom Field Values)

34. Help Texts

35. Project Phases & Definitions

36. Previewing (Markup Preview)

37. Schemas

38. User Preferences

39. Values (String Objects)

40. Root & Configuration

Configuration Properties:

• Maximum attachment file size

• Host name

• Per-page options

• Duration format

• Active feature flags

41. OAuth 2.0

MCP Server Implementation Details

Tool Implementation Pattern

Each tool follows a consistent implementation pattern:

Resource Implementation

Resources provide read-only access to OpenProject data:

Prompt Templates

Pre-built prompts for common operations:

Configuration

Prerequisites

Before configuring the MCP server, ensure you have:

1. Bun installed - The server requires Bun runtime

   # Install Bun (macOS, Linux, WSL) curl -fsSL https://bun.sh/install | bash # Or using npm npm install -g bun

2. OpenProject API Key - Generate one from your OpenProject instance:

   • Navigate to your OpenProject instance

   • Go to "My account" → "Access tokens"

   • Click "Generate" and copy the API key

   • Store it securely (you won't be able to see it again)

3. Clone this repository:

   git clone https://github.com/yourusername/tonle.git cd tonle bun install

Environment Variables

The server requires these environment variables:

Note: The current implementation reads environment variables directly. Advanced configuration features (rate limiting, retries) are planned for future releases.

MCP Client Configuration

Claude Desktop

Claude Desktop is Anthropic's official desktop application with built-in MCP support.

Configuration Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration

Edit or create the claude_desktop_config.json file:

Important:

• Use the absolute path to your index.ts file

• Replace your-instance.openproject.com with your actual OpenProject URL

• Replace your-api-key-here with your generated API key

• Restart Claude Desktop after configuration changes

Verification

1. Restart Claude Desktop

2. Look for the 🔌 icon in the bottom-right corner

3. Click it to see available MCP servers

4. You should see "openproject" listed with available tools

5. Try asking: "List all my OpenProject projects"

Claude Code (CLI)

Claude Code is Anthropic's official command-line interface with built-in MCP support.

Installation

Configuration Location

• macOS: ~/.config/claude-code/config.json

• Windows: %APPDATA%\claude-code\config.json

• Linux: ~/.config/claude-code/config.json

Configuration

Edit or create the config.json file:

Usage

After configuration, start Claude Code:

The OpenProject MCP server will automatically connect when you start Claude Code.

Verification

1. Start Claude Code CLI

2. Check for connection messages in the terminal

3. Try asking: "List all OpenProject tools available"

4. Test with: "Show me my OpenProject projects"

Tips

• Use claude-code --help to see all available options

• Check logs with claude-code --verbose for debugging

• The CLI respects the same configuration format as Claude Desktop

Cursor IDE

Cursor is an AI-powered code editor with MCP support.

Configuration Location

• All platforms: .cursor/mcp.json in your project root or home directory

Configuration

Create or edit .cursor/mcp.json:

Note: Check Cursor's documentation for the latest MCP configuration format as it may evolve.

Windsurf IDE

Windsurf is an AI-powered development environment with MCP support.

Configuration

Windsurf typically uses a similar configuration format. Check the Windsurf documentation for:

• Configuration file location

• MCP server registration format

• Environment variable handling

Expected configuration format:

MCP Inspector (Development & Testing)

The MCP Inspector is a browser-based tool for testing and debugging MCP servers.

Installation & Usage

What You Can Do

• Test Tools: Execute any tool with custom parameters

• View Responses: See raw JSON responses from the OpenProject API

• Debug Errors: Inspect error messages and stack traces

• Explore Schema: View input/output schemas for all tools

Inspector Workflow

1. Start the Inspector (it will open in your browser)

2. The server will automatically connect

3. Browse available tools in the left sidebar

4. Select a tool to see its parameters

5. Fill in parameters and click "Execute"

6. View the response in the output panel

Pro Tip: Use the Inspector to test your OpenProject connection before configuring client applications.

HTTP Transport (Remote/Web Clients)

The MCP server supports HTTP transport using the Streamable HTTP protocol, enabling remote connections from web-based clients or distributed systems.

Starting the HTTP Server

Environment Variables

HTTP Endpoints

Testing the HTTP Server

Use curl to verify the server is running:

Programmatic HTTP Client Integration

MCP Inspector with HTTP Transport

Deploying the HTTP Server

For production deployments:

1. Using a process manager (PM2):

   pm2 start "bun run start:http" --name openproject-mcp

2. Using Docker:

   FROM oven/bun:1 WORKDIR /app COPY . . RUN bun install ENV MCP_HTTP_PORT=3100 EXPOSE 3100 CMD ["bun", "run", "start:http"]

3. Behind a reverse proxy (nginx):

   location /mcp { proxy_pass http://localhost:3100; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; }

Configuring MCP Clients to Use HTTP Transport

Many MCP clients (IDEs, CLIs, or custom applications) can connect to a remote MCP server over HTTP instead of spawning it via stdio.

• 1. Start the HTTP server: Run bun run start:http (or MCP_HTTP_PORT=3100 bun run start:http) on the machine where the OpenProject MCP server is hosted.

• 2. Expose the : Ensure http://HOST:PORT/mcp is reachable from your MCP client (optionally via reverse proxy, VPN, or SSH tunnel).

• 3. Configure the client for HTTP:

  • Point the client to http://HOST:PORT/mcp as the MCP endpoint.

  • Select HTTP/Streamable HTTP (or equivalent) as the transport type in your client's configuration.

  • Keep OPENPROJECT_URL and OPENPROJECT_API_KEY configured only on the server side; the client never needs the OpenProject API key.

• 4. Verify the connection:

  • Use your client's "list tools" or "introspect MCP servers" feature to confirm that the openproject tools are visible.

  • Call a simple tool such as get_current_user or list_projects to confirm end-to-end HTTP connectivity.

The exact JSON configuration format (for example, in claude_desktop_config.json, .cursor/mcp.json, or other clients) depends on the specific MCP client you use. Refer to your client's documentation for the current syntax for registering HTTP-based MCP servers, using http://HOST:PORT/mcp as the server URL.

Example mcpServers Configuration with HTTP Protocol

For clients that support HTTP transport configuration, use the following format:

Remote Server Configuration:

Notes:

• The type field specifies HTTP transport (may vary by client: "http", "streamable-http", or "sse")

• Environment variables in env are passed to the HTTP server when applicable

• For remote servers, ensure the endpoint is accessible and properly secured (HTTPS recommended)

• The OpenProject credentials (OPENPROJECT_URL and OPENPROJECT_API_KEY) should be configured on the server side, not in the client configuration

Custom MCP Clients

The server supports two transport mechanisms:

Option 1: STDIO Transport (Local/Subprocess)

Best for local development and desktop applications that spawn the server as a subprocess.

1. Protocol: Standard input/output streams

2. Command: bun run /path/to/tonle/index.ts

3. Environment Variables: Pass OPENPROJECT_URL and OPENPROJECT_API_KEY

4. Protocol Version: MCP SDK version 1.22.0

Option 2: HTTP Transport (Remote/Web)

Best for web applications, remote clients, or microservice architectures.

1. Protocol: Streamable HTTP (JSON-RPC over HTTP with SSE)

2. URL: http://your-server:3100/mcp

3. Environment Variables: Set on the server side

4. Protocol Version: MCP SDK version 1.22.0

Testing Your Configuration

Quick Connection Test

After configuring your MCP client, test the connection:

1. List all tools: Ask your AI assistant to show available OpenProject tools

2. Get current user: Try get_current_user tool to verify authentication

3. List projects: Try list_projects to confirm API access

Example Queries

Try these natural language queries:

• "Show me all my OpenProject projects"

• "List work packages in project X"

• "Create a new task in project Y with title 'Setup testing environment'"

• "Who is the current authenticated user?"

• "Show me all work package types available"

Troubleshooting

Viewing Server Logs

When running via MCP clients, server logs (from console.error()) typically appear in:

• Claude Desktop: View → Developer → Toggle Developer Tools → Console

• MCP Inspector: Visible in the terminal where you ran the inspector

• Cursor/Windsurf: Check the IDE's output/debug panels

Advanced Configuration

Using Environment Files

For development, create a .env file (never commit this):

Load it before running:

Multiple OpenProject Instances

To connect to multiple OpenProject instances, create separate server entries:

Docker Deployment

While the server primarily uses stdio transport (local only), future HTTP transport support will enable Docker deployment:

Note: HTTP transport implementation is planned for future releases.

Security Considerations

Authentication

1. API Key Security: API keys should be stored securely using environment variables or secret management systems

2. OAuth 2.0: Support for OAuth 2.0 with authorization code flow and PKCE

3. Session Management: Proper handling of session tokens with secure refresh mechanisms

Authorization

• All operations respect OpenProject's permission system

• Tools only expose actions the authenticated user is authorized to perform

• Sensitive operations require explicit confirmation

Data Protection

• HTTPS enforcement for all API communications

• No sensitive data logging

• Request/response payload sanitization

Error Handling

Standard Error Responses

Error Recovery

• Automatic retry with exponential backoff for transient errors

• Clear error messages with actionable suggestions

• Graceful degradation for non-critical failures

Testing Strategy

Unit Tests

• Individual tool handler testing

• Schema validation testing

• Error handling verification

Integration Tests

• Full API endpoint testing against OpenProject test instance

• Authentication flow testing

• Rate limiting behavior verification

End-to-End Tests

• Complete workflow testing with MCP Inspector

• Claude Desktop integration testing

• Performance benchmarking

Deployment Options

Local Development

Docker Deployment

Kubernetes Deployment

Project Roadmap

Phase 1: Core Implementation (MVP)

• Project setup and configuration

• OpenProject API client implementation

• Work packages CRUD tools

• Projects CRUD tools

• Basic authentication (API key)

• Stdio transport support

Phase 2: Extended Coverage

• All remaining endpoint implementations

• OAuth 2.0 authentication

• Resource providers

• Prompt templates

• HTTP transport support

Phase 3: Enterprise Features

• Rate limiting and throttling

• Caching layer

• Audit logging

• Multi-instance support

• SSO integration

Phase 4: Advanced Features

• Webhook event handling

• Real-time notifications via SSE

• Batch operations

• Advanced filtering DSL

• AI-assisted project planning prompts

Contributing

Development Setup

Code Style

• ESLint with TypeScript rules

• Prettier for formatting

• Conventional commits for changelog generation

Pull Request Process

1. Create feature branch from main

2. Implement changes with tests

3. Ensure all tests pass

4. Update documentation

5. Submit PR with detailed description

License

MIT License - See LICENSE file for details

Acknowledgments

• OpenProject GmbH for the excellent open-source project management software

• Anthropic for developing the Model Context Protocol

• MCP Community for tooling and best practices

Support & Resources

• OpenProject Documentation: https://www.openproject.org/docs/

• OpenProject API Reference: https://www.openproject.org/docs/api/

• MCP Specification: https://spec.modelcontextprotocol.io/

• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

This project description was created as a comprehensive blueprint for implementing a full-featured MCP server for OpenProject. The implementation covers all available API endpoints to provide complete project management capabilities through AI assistants.