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:

bun install

To run:

bun run index.ts

┌─────────────────────────────────────────────────────────────┐
│                    MCP-Compatible Clients                    │
│         (Claude Desktop, Cursor, Windsurf, etc.)            │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ MCP Protocol (JSON-RPC 2.0)
                              │
┌─────────────────────────────────────────────────────────────┐
│                  OpenProject MCP Server                      │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Transport Layer                       ││
│  │         (Stdio / Streamable HTTP / WebSocket)           ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                   MCP Server Core                        ││
│  │    (@modelcontextprotocol/sdk TypeScript SDK)           ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                   Tool Registry                          ││
│  │      (Tool definitions, schemas, handlers)              ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                Resource Provider                         ││
│  │   (Dynamic data exposure for projects, users, etc.)     ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │               OpenProject API Client                     ││
│  │        (HAL+JSON API v3 communication layer)            ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTPS (HAL+JSON)
                              │
┌─────────────────────────────────────────────────────────────┐
│                   OpenProject Instance                       │
│                      (API v3 Endpoints)                      │
└─────────────────────────────────────────────────────────────┘

Core Technologies

Component	Technology	Purpose
Runtime	Bun	Server execution environment
Language	TypeScript 5.x	Type-safe development
MCP SDK	@modelcontextprotocol/sdk	MCP protocol implementation
Validation	Zod	Runtime schema validation
HTTP Client	Axios/Fetch	OpenProject API communication
Testing	Vitest	Unit and integration testing
Documentation	TypeDoc	API documentation generation

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.

Tool Name	HTTP Method	Endpoint	Description
list_work_packages	GET	/api/v3/work_packages	List all work packages with filtering
get_work_package	GET	/api/v3/work_packages/{id}	Get a single work package
create_work_package	POST	/api/v3/work_packages	Create a new work package
update_work_package	PATCH	/api/v3/work_packages/{id}	Update an existing work package
delete_work_package	DELETE	/api/v3/work_packages/{id}	Delete a work package
get_work_package_form	POST	/api/v3/work_packages/form	Get form for creating work packages
get_work_package_update_form	POST	/api/v3/work_packages/{id}/form	Get form for updating work packages
list_project_work_packages	GET	/api/v3/projects/{id}/work_packages	List work packages in a project
create_project_work_package	POST	/api/v3/projects/{id}/work_packages	Create work package in a project
get_work_package_schema	GET	/api/v3/work_packages/schemas/{id}	Get work package schema
list_work_package_schemas	GET	/api/v3/work_packages/schemas	List all work package schemas
get_available_watchers	GET	/api/v3/work_packages/{id}/available_watchers	Get users who can watch
list_watchers	GET	/api/v3/work_packages/{id}/watchers	List work package watchers
add_watcher	POST	/api/v3/work_packages/{id}/watchers	Add a watcher
remove_watcher	DELETE	/api/v3/work_packages/{id}/watchers/{user_id}	Remove a watcher
list_available_assignees	GET	/api/v3/projects/{id}/available_assignees	Get assignable users
list_available_responsibles	GET	/api/v3/projects/{id}/available_responsibles	Get responsible users
execute_custom_action	POST	/api/v3/work_packages/{id}/custom_actions/{action_id}/execute	Execute custom action

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.

Tool Name	HTTP Method	Endpoint	Description
list_projects	GET	/api/v3/projects	List all visible projects
get_project	GET	/api/v3/projects/{id}	Get a single project
create_project	POST	/api/v3/projects	Create a new project
update_project	PATCH	/api/v3/projects/{id}	Update a project
delete_project	DELETE	/api/v3/projects/{id}	Delete a project
get_project_form	POST	/api/v3/projects/form	Get form for creating projects
get_project_update_form	POST	/api/v3/projects/{id}/form	Get form for updating projects
copy_project	POST	/api/v3/projects/{id}/copy	Copy an existing project
list_project_statuses	GET	/api/v3/project_statuses	List available project statuses
get_project_status	GET	/api/v3/project_statuses/{id}	Get a project status

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

Tool Name	HTTP Method	Endpoint	Description
list_users	GET	/api/v3/users	List all users
get_user	GET	/api/v3/users/{id}	Get a single user
create_user	POST	/api/v3/users	Create a new user
update_user	PATCH	/api/v3/users/{id}	Update a user
delete_user	DELETE	/api/v3/users/{id}	Delete a user
lock_user	POST	/api/v3/users/{id}/lock	Lock a user account
unlock_user	DELETE	/api/v3/users/{id}/lock	Unlock a user account
get_current_user	GET	/api/v3/users/me	Get the authenticated user

User Properties:

• Login, email, first name, last name
• Admin status
• Status (active, registered, locked, invited)
• Avatar, language preference
• Identity URL (for SSO)

---

4. Groups

Tool Name	HTTP Method	Endpoint	Description
list_groups	GET	/api/v3/groups	List all groups
get_group	GET	/api/v3/groups/{id}	Get a single group
create_group	POST	/api/v3/groups	Create a new group
update_group	PATCH	/api/v3/groups/{id}	Update a group
delete_group	DELETE	/api/v3/groups/{id}	Delete a group

---

5. Principals (Users, Groups, Placeholder Users)

Tool Name	HTTP Method	Endpoint	Description
list_principals	GET	/api/v3/principals	List all principals
list_placeholder_users	GET	/api/v3/placeholder_users	List placeholder users
get_placeholder_user	GET	/api/v3/placeholder_users/{id}	Get a placeholder user
create_placeholder_user	POST	/api/v3/placeholder_users	Create placeholder user
update_placeholder_user	PATCH	/api/v3/placeholder_users/{id}	Update placeholder user
delete_placeholder_user	DELETE	/api/v3/placeholder_users/{id}	Delete placeholder user

---

6. Memberships

Tool Name	HTTP Method	Endpoint	Description
list_memberships	GET	/api/v3/memberships	List all memberships
list_project_members	GET	/api/v3/memberships?filters=[{"project":{"operator":"=","values":["{projectId}"]}}]	List members within a project
list_work_package_members	GET	/api/v3/memberships?filters=[{"project":{"operator":"=","values":["project_of_work_package"]}}]	List members of the project owning a work package
get_membership	GET	/api/v3/memberships/{id}	Get a single membership
create_membership	POST	/api/v3/memberships	Create a membership
update_membership	PATCH	/api/v3/memberships/{id}	Update a membership
delete_membership	DELETE	/api/v3/memberships/{id}	Delete a membership
get_membership_form	POST	/api/v3/memberships/form	Get form for memberships
get_membership_schema	GET	/api/v3/memberships/schema	Get membership schema

Membership Features:

• Custom notification messages on create/update
• Multiple role assignment
• Project-specific permissions

---

7. Roles

Tool Name	HTTP Method	Endpoint	Description
list_roles	GET	/api/v3/roles	List all roles
get_role	GET	/api/v3/roles/{id}	Get a single role

---

8. Time Entries

Tool Name	HTTP Method	Endpoint	Description
list_time_entries	GET	/api/v3/time_entries	List all time entries
get_time_entry	GET	/api/v3/time_entries/{id}	Get a single time entry
create_time_entry	POST	/api/v3/time_entries	Create a time entry
update_time_entry	PATCH	/api/v3/time_entries/{id}	Update a time entry
delete_time_entry	DELETE	/api/v3/time_entries/{id}	Delete a time entry
get_time_entry_form	POST	/api/v3/time_entries/form	Get form for time entries
get_time_entry_schema	GET	/api/v3/time_entries/schema	Get time entry schema

---

9. Time Entry Activities

Tool Name	HTTP Method	Endpoint	Description
get_time_entry_activity	GET	/api/v3/time_entries/activities/{id}	Get a time entry activity

---

10. Activities (Journal Entries)

Tool Name	HTTP Method	Endpoint	Description
get_activity	GET	/api/v3/activities/{id}	Get an activity
update_activity	PATCH	/api/v3/activities/{id}	Update activity comment
list_work_package_activities	GET	/api/v3/work_packages/{id}/activities	List work package activities

Activity Features:

• Internal/external visibility
• Attachments on comments
• Emoji reactions

---

11. Attachments

Tool Name	HTTP Method	Endpoint	Description
get_attachment	GET	/api/v3/attachments/{id}	Get an attachment
delete_attachment	DELETE	/api/v3/attachments/{id}	Delete an attachment
upload_attachment	POST	/api/v3/attachments	Upload a new attachment
list_work_package_attachments	GET	/api/v3/work_packages/{id}/attachments	List work package attachments
add_work_package_attachment	POST	/api/v3/work_packages/{id}/attachments	Add attachment to work package
list_activity_attachments	GET	/api/v3/activities/{id}/attachments	List activity attachments
add_activity_attachment	POST	/api/v3/activities/{id}/attachments	Add attachment to activity

Attachment Features:

• Multipart upload with metadata
• Containerless attachments (upload then claim)
• Download location links
• Content type and file size information

---

12. Versions (Releases/Milestones)

Tool Name	HTTP Method	Endpoint	Description
list_versions	GET	/api/v3/versions	List all versions
get_version	GET	/api/v3/versions/{id}	Get a single version
create_version	POST	/api/v3/versions	Create a version
update_version	PATCH	/api/v3/versions/{id}	Update a version
delete_version	DELETE	/api/v3/versions/{id}	Delete a version
list_project_versions	GET	/api/v3/projects/{id}/versions	List project versions
get_version_form	POST	/api/v3/versions/form	Get form for versions
get_available_projects_for_versions	GET	/api/v3/versions/available_projects	Get projects for version creation

Version Properties:

• Name, description, status
• Start date, end date
• Sharing scope (none, descendants, hierarchy, tree, system)
• Custom fields

---

13. Categories

Tool Name	HTTP Method	Endpoint	Description
list_categories	GET	/api/v3/categories	List all categories
get_category	GET	/api/v3/categories/{id}	Get a single category
list_project_categories	GET	/api/v3/projects/{id}/categories	List project categories

---

14. Types (Work Package Types)

Tool Name	HTTP Method	Endpoint	Description
list_types	GET	/api/v3/types	List all work package types
get_type	GET	/api/v3/types/{id}	Get a single type
list_project_types	GET	/api/v3/projects/{id}/types	List types available in a project

Type Properties:

• Name, color, position
• Is default, is milestone
• Attribute groups and visibility

---

15. Statuses (Work Package Statuses)

Tool Name	HTTP Method	Endpoint	Description
list_statuses	GET	/api/v3/statuses	List all statuses
get_status	GET	/api/v3/statuses/{id}	Get a single status

Status Properties:

• Name, color, position
• Is closed, is default, is readonly

---

16. Priorities

Tool Name	HTTP Method	Endpoint	Description
list_priorities	GET	/api/v3/priorities	List all priorities
get_priority	GET	/api/v3/priorities/{id}	Get a single priority

---

17. Relations

Tool Name	HTTP Method	Endpoint	Description
list_relations	GET	/api/v3/relations	List all relations
get_relation	GET	/api/v3/relations/{id}	Get a single relation
create_relation	POST	/api/v3/relations	Create a relation
update_relation	PATCH	/api/v3/relations/{id}	Update a relation
delete_relation	DELETE	/api/v3/relations/{id}	Delete a relation
list_work_package_relations	GET	/api/v3/work_packages/{id}/relations	List work package relations

Relation Types:

• relates, duplicates, duplicated, blocks, blocked
• precedes, follows, includes, partof, requires, required

---

18. Queries (Saved Filters)

Tool Name	HTTP Method	Endpoint	Description
list_queries	GET	/api/v3/queries	List all queries
get_query	GET	/api/v3/queries/{id}	Get a single query
create_query	POST	/api/v3/queries	Create a query
update_query	PATCH	/api/v3/queries/{id}	Update a query
delete_query	DELETE	/api/v3/queries/{id}	Delete a query
get_default_query	GET	/api/v3/queries/default	Get the default query
star_query	PATCH	/api/v3/queries/{id}/star	Star a query
unstar_query	PATCH	/api/v3/queries/{id}/unstar	Unstar a query

---

19. Query Filters, Columns, Operators, Sort Bys

Tool Name	HTTP Method	Endpoint	Description
list_query_filters	GET	/api/v3/queries/filters	List available filters
get_query_filter	GET	/api/v3/queries/filters/{id}	Get a single filter
list_query_columns	GET	/api/v3/queries/columns	List available columns
get_query_column	GET	/api/v3/queries/columns/{id}	Get a single column
list_query_operators	GET	/api/v3/queries/operators	List available operators
get_query_operator	GET	/api/v3/queries/operators/{id}	Get a single operator
list_query_sort_bys	GET	/api/v3/queries/sort_bys	List available sort options
get_query_sort_by	GET	/api/v3/queries/sort_bys/{id}	Get a single sort option
get_query_filter_instance_schema	GET	/api/v3/queries/filter_instance_schemas/{id}	Get filter instance schema

---

20. Views

Tool Name	HTTP Method	Endpoint	Description
list_views	GET	/api/v3/views	List all views
get_view	GET	/api/v3/views/{id}	Get a single view
create_work_packages_table_view	POST	/api/v3/views/work_packages_table	Create table view
create_team_planner_view	POST	/api/v3/views/team_planner	Create team planner view
create_gantt_view	POST	/api/v3/views/gantt	Create Gantt view

---

21. Notifications

Tool Name	HTTP Method	Endpoint	Description
list_notifications	GET	/api/v3/notifications	List all notifications
get_notification	GET	/api/v3/notifications/{id}	Get a single notification
mark_notification_read	POST	/api/v3/notifications/{id}/read_ian	Mark as read
mark_notification_unread	POST	/api/v3/notifications/{id}/unread_ian	Mark as unread
mark_all_notifications_read	POST	/api/v3/notifications/read_ian	Mark all as read
mark_all_notifications_unread	POST	/api/v3/notifications/unread_ian	Mark all as unread

Notification Reasons:

• mentioned, assigned, responsible, watched
• dateAlert, commented, created, scheduled

---

22. News

Tool Name	HTTP Method	Endpoint	Description
list_news	GET	/api/v3/news	List all news articles
get_news	GET	/api/v3/news/{id}	Get a single news article
list_project_news	GET	/api/v3/projects/{id}/news	List project news

---

23. Posts (Forum Messages)

Tool Name	HTTP Method	Endpoint	Description
get_post	GET	/api/v3/posts/{id}	Get a forum post

---

24. Wiki Pages

Tool Name	HTTP Method	Endpoint	Description
get_wiki_page	GET	/api/v3/wiki_pages/{id}	Get a wiki page
update_wiki_page	PUT	/api/v3/wiki_pages/{id}	Update a wiki page

---

25. Documents

Tool Name	HTTP Method	Endpoint	Description
list_documents	GET	/api/v3/documents	List all documents
get_document	GET	/api/v3/documents/{id}	Get a single document
list_project_documents	GET	/api/v3/projects/{id}/documents	List project documents

---

26. Budgets

Tool Name	HTTP Method	Endpoint	Description
get_budget	GET	/api/v3/budgets/{id}	Get a single budget
list_project_budgets	GET	/api/v3/projects/{id}/budgets	List project budgets

---

27. Revisions (Repository Commits)

Tool Name	HTTP Method	Endpoint	Description
get_revision	GET	/api/v3/revisions/{id}	Get a revision
list_work_package_revisions	GET	/api/v3/work_packages/{id}/revisions	List work package revisions

---

28. File Links & Storages (External File Integration)

Tool Name	HTTP Method	Endpoint	Description
list_storages	GET	/api/v3/storages	List all storages
get_storage	GET	/api/v3/storages/{id}	Get a single storage
create_storage	POST	/api/v3/storages	Create a storage
update_storage	PATCH	/api/v3/storages/{id}	Update a storage
delete_storage	DELETE	/api/v3/storages/{id}	Delete a storage
create_oauth_client_credentials	POST	/api/v3/storages/{id}/oauth_client_credentials	Create OAuth credentials
list_project_storages	GET	/api/v3/project_storages	List project storages
get_project_storage	GET	/api/v3/project_storages/{id}	Get a project storage
list_file_links	GET	/api/v3/work_packages/{id}/file_links	List file links
create_file_link	POST	/api/v3/work_packages/{id}/file_links	Create a file link
get_file_link	GET	/api/v3/file_links/{id}	Get a file link
delete_file_link	DELETE	/api/v3/file_links/{id}	Delete a file link

Supported Storage Types:

• Nextcloud
• OneDrive/SharePoint

---

29. Grids (Dashboard Layouts)

Tool Name	HTTP Method	Endpoint	Description
list_grids	GET	/api/v3/grids	List all grids
get_grid	GET	/api/v3/grids/{id}	Get a single grid
create_grid	POST	/api/v3/grids	Create a grid
update_grid	PATCH	/api/v3/grids/{id}	Update a grid
get_grid_form	POST	/api/v3/grids/form	Get form for grids

Grid Widgets:

• time_entries_current_user
• news, documents
• work_packages_table
• and more...

---

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

Tool Name	HTTP Method	Endpoint	Description
list_days	GET	/api/v3/days	List days with working status
get_day	GET	/api/v3/days/{date}	Get a single day
list_week_days	GET	/api/v3/days/week	List week days
get_week_day	GET	/api/v3/days/week/{day}	Get a week day
update_week_days	PATCH	/api/v3/days/week	Update week day settings
list_non_working_days	GET	/api/v3/days/non_working	List non-working days
get_non_working_day	GET	/api/v3/days/non_working/{date}	Get a non-working day
create_non_working_day	POST	/api/v3/days/non_working	Create non-working day
update_non_working_day	PATCH	/api/v3/days/non_working/{date}	Update non-working day
delete_non_working_day	DELETE	/api/v3/days/non_working/{date}	Delete non-working day

---

31. Actions & Capabilities

Tool Name	HTTP Method	Endpoint	Description
list_actions	GET	/api/v3/actions	List all actions
get_action	GET	/api/v3/actions/{id}	Get a single action
list_capabilities	GET	/api/v3/capabilities	List user capabilities
get_capability	GET	/api/v3/capabilities/{id}	Get a capability

---

32. Custom Actions

Tool Name	HTTP Method	Endpoint	Description
get_custom_action	GET	/api/v3/custom_actions/{id}	Get a custom action
execute_custom_action	POST	/api/v3/custom_actions/{id}/execute	Execute custom action

---

33. Custom Options (Custom Field Values)

Tool Name	HTTP Method	Endpoint	Description
get_custom_option	GET	/api/v3/custom_options/{id}	Get a custom option

---

34. Help Texts

Tool Name	HTTP Method	Endpoint	Description
list_help_texts	GET	/api/v3/help_texts	List all help texts
get_help_text	GET	/api/v3/help_texts/{id}	Get a single help text

---

35. Project Phases & Definitions

Tool Name	HTTP Method	Endpoint	Description
list_project_phases	GET	/api/v3/project_phases	List project phases
get_project_phase	GET	/api/v3/project_phases/{id}	Get a project phase
list_project_phase_definitions	GET	/api/v3/project_phase_definitions	List phase definitions
get_project_phase_definition	GET	/api/v3/project_phase_definitions/{id}	Get phase definition

---

36. Previewing (Markup Preview)

Tool Name	HTTP Method	Endpoint	Description
preview_markup	POST	/api/v3/render/markdown	Preview markdown
preview_plain	POST	/api/v3/render/plain	Preview plain text

---

37. Schemas

Tool Name	HTTP Method	Endpoint	Description
get_schema	GET	/api/v3/schemas/{schema_id}	Get a specific schema

---

38. User Preferences

Tool Name	HTTP Method	Endpoint	Description
get_user_preferences	GET	/api/v3/my_preferences	Get current user preferences
update_user_preferences	PATCH	/api/v3/my_preferences	Update user preferences

---

39. Values (String Objects)

Tool Name	HTTP Method	Endpoint	Description
get_string_object	GET	/api/v3/string_objects	Get string object value

---

40. Root & Configuration

Tool Name	HTTP Method	Endpoint	Description
get_root	GET	/api/v3	Get API root
get_configuration	GET	/api/v3/configuration	Get instance configuration

Configuration Properties:

• Maximum attachment file size
• Host name
• Per-page options
• Duration format
• Active feature flags

---

41. OAuth 2.0

Tool Name	HTTP Method	Endpoint	Description
list_oauth_applications	GET	/api/v3/oauth_applications	List OAuth applications
get_oauth_application	GET	/api/v3/oauth_applications/{id}	Get OAuth application
create_oauth_application	POST	/api/v3/oauth_applications	Create OAuth application
delete_oauth_application	DELETE	/api/v3/oauth_applications/{id}	Delete OAuth application
list_oauth_client_credentials	GET	/api/v3/oauth_client_credentials	List client credentials

---

MCP Server Implementation Details

Tool Implementation Pattern

Each tool follows a consistent implementation pattern:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

// Tool registration example
server.registerTool(
  'create_work_package',
  {
    title: 'Create Work Package',
    description: 'Creates a new work package in OpenProject with specified properties',
    inputSchema: {
      project_id: z.number().describe('The ID of the project'),
      subject: z.string().describe('The subject/title of the work package'),
      type_id: z.number().optional().describe('The work package type ID'),
      description: z.string().optional().describe('Detailed description (supports markdown)'),
      assignee_id: z.number().optional().describe('User ID of the assignee'),
      priority_id: z.number().optional().describe('Priority ID'),
      start_date: z.string().optional().describe('Start date (ISO 8601)'),
      due_date: z.string().optional().describe('Due date (ISO 8601)'),
      estimated_hours: z.number().optional().describe('Estimated hours'),
      notify: z.boolean().optional().default(true).describe('Send notifications'),
    },
    outputSchema: {
      id: z.number(),
      subject: z.string(),
      project: z.object({ id: z.number(), name: z.string() }),
      status: z.object({ id: z.number(), name: z.string() }),
      _links: z.object({
        self: z.object({ href: z.string() })
      })
    }
  },
  async (params) => {
    const response = await openProjectClient.createWorkPackage(params);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(response, null, 2)
      }]
    };
  }
);

Resource Implementation

Resources provide read-only access to OpenProject data:

// Resource registration example
server.resource(
  'projects',
  'openproject://projects',
  {
    name: 'OpenProject Projects',
    description: 'List of all accessible projects',
    mimeType: 'application/json'
  },
  async () => {
    const projects = await openProjectClient.listProjects();
    return {
      contents: [{
        uri: 'openproject://projects',
        mimeType: 'application/json',
        text: JSON.stringify(projects, null, 2)
      }]
    };
  }
);

Prompt Templates

Pre-built prompts for common operations:

// Prompt registration example
server.prompt(
  'create_sprint_backlog',
  {
    name: 'Create Sprint Backlog',
    description: 'Template for creating work packages for a sprint',
    arguments: [
      { name: 'project_id', description: 'Project ID', required: true },
      { name: 'sprint_name', description: 'Sprint name', required: true },
      { name: 'tasks', description: 'JSON array of task titles', required: true }
    ]
  },
  async ({ project_id, sprint_name, tasks }) => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `Create work packages in project ${project_id} for sprint "${sprint_name}" with these tasks: ${tasks}`
        }
      }]
    };
  }
);

---

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:

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

# Optional
OPENPROJECT_TIMEOUT=30000  # Request timeout in milliseconds (default: 30000)

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:

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

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

# Install Claude Code CLI globally
npm install -g @anthropic-ai/claude-code

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:

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage

After configuration, start Claude Code:

# Start Claude Code
claude-code

# Or start in a specific directory
claude-code /path/to/your/project

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:

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

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:

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

MCP Inspector (Development & Testing)

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

Installation & Usage

# Run the server with Inspector
bun run inspect

# Or manually
bunx @modelcontextprotocol/inspector bun run index.ts

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

# Start the HTTP server (default port 3100)
bun run start:http

# Or with custom port
MCP_HTTP_PORT=8080 bun run start:http

# Development mode with hot reload
bun run dev:http

Environment Variables

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

# Optional
MCP_HTTP_PORT=3100        # HTTP server port (default: 3100)
MCP_HTTP_HOST=0.0.0.0     # HTTP server host (default: 0.0.0.0)
OPENPROJECT_TIMEOUT=30000 # Request timeout in milliseconds

HTTP Endpoints

Endpoint	Method	Description
/mcp	POST	Handle MCP JSON-RPC requests
/mcp	GET	Get session status
/mcp	DELETE	Close a session
/health	GET	Health check endpoint

Testing the HTTP Server

Use curl to verify the server is running:

# Health check
curl http://localhost:3100/health
# Response: {"status":"ok","transport":"http"}

# Initialize a session
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0.0"}
    }
  }'

Programmatic HTTP Client Integration

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

// Connect via HTTP
const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:3100/mcp')
);

const client = new Client({
  name: 'my-http-client',
  version: '1.0.0',
});

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));

// Call a tool
const result = await client.callTool({
  name: 'get_current_user',
  arguments: {},
});
console.log('Current user:', result.content);

// Close the connection
await client.close();

MCP Inspector with HTTP Transport

# Inspect the HTTP server
bun run inspect:http

# Or manually
bunx @modelcontextprotocol/inspector --transport http --url http://localhost:3100/mcp

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 /mcp endpoint: 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:

{
  "mcpServers": {
    "openproject": {
      "type": "http",
      "url": "http://localhost:3100/mcp",
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Remote Server Configuration:

{
  "mcpServers": {
    "openproject": {
      "type": "http",
      "url": "https://your-server.example.com/mcp",
      "env": {
        "MCP_HTTP_PORT": "3100",
        "MCP_HTTP_HOST": "0.0.0.0"
      }
    }
  }
}

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

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'bun',
  args: ['run', '/path/to/tonle/index.ts'],
  env: {
    OPENPROJECT_URL: 'https://your-instance.openproject.com',
    OPENPROJECT_API_KEY: 'your-api-key',
  },
});

const client = new Client({
  name: 'my-mcp-client',
  version: '1.0.0',
});

await client.connect(transport);
const tools = await client.listTools();

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

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('http://your-server:3100/mcp')
);

const client = new Client({
  name: 'my-http-client',
  version: '1.0.0',
});

await client.connect(transport);
const tools = await client.listTools();

---

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

Issue	Solution
Server not appearing in client	Check absolute path to index.ts, restart client
Authentication errors	Verify API key is correct and has proper permissions
Connection timeout	Check OPENPROJECT_URL is accessible and correct
Bun command not found	Ensure Bun is installed and in your PATH
Tools not loading	Check server logs for errors, verify OpenProject instance is running

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):

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

Load it before running:

# Using bun's built-in env support
bun run index.ts

# Or manually
export $(cat .env | xargs) && bun run index.ts

Multiple OpenProject Instances

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

{
  "mcpServers": {
    "openproject-production": {
      "command": "bun",
      "args": ["run", "/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://prod.openproject.com",
        "OPENPROJECT_API_KEY": "prod-api-key"
      }
    },
    "openproject-staging": {
      "command": "bun",
      "args": ["run", "/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://staging.openproject.com",
        "OPENPROJECT_API_KEY": "staging-api-key"
      }
    }
  }
}

Docker Deployment

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

FROM oven/bun:1
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --production
COPY . .
ENV OPENPROJECT_URL=""
ENV OPENPROJECT_API_KEY=""
CMD ["bun", "run", "index.ts"]

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

interface OpenProjectError {
  _type: 'Error';
  errorIdentifier: string;
  message: string;
  _embedded?: {
    details?: {
      attribute?: string;
    };
  };
}

// Common error identifiers
const ERROR_CODES = {
  NOT_FOUND: 'urn:openproject-org:api:v3:errors:NotFound',
  UNAUTHORIZED: 'urn:openproject-org:api:v3:errors:Unauthenticated',
  FORBIDDEN: 'urn:openproject-org:api:v3:errors:MissingPermission',
  VALIDATION: 'urn:openproject-org:api:v3:errors:PropertyConstraintViolation',
  CONFLICT: 'urn:openproject-org:api:v3:errors:UpdateConflict',
  INVALID_BODY: 'urn:openproject-org:api:v3:errors:InvalidRequestBody'
};

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

# Clone and install
git clone https://github.com/your-org/openproject-mcp-server.git
cd openproject-mcp-server
bun install

# Run with stdio transport (Bun + TypeScript)
bun run index.ts

# Test with MCP Inspector
bunx @modelcontextprotocol/inspector bun run index.ts

Docker Deployment

FROM oven/bun:1
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --production
COPY . .
EXPOSE 3000
CMD ["bun", "run", "index.ts"]

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: openproject-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: openproject-mcp
  template:
    metadata:
      labels:
        app: openproject-mcp
    spec:
      containers:
      - name: mcp-server
        image: your-registry/openproject-mcp-server:latest
        ports:
        - containerPort: 3000
        env:
        - name: OPENPROJECT_URL
          valueFrom:
            secretKeyRef:
              name: openproject-secrets
              key: url
        - name: OPENPROJECT_API_KEY
          valueFrom:
            secretKeyRef:
              name: openproject-secrets
              key: api-key

---

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

# Fork and clone
git clone https://github.com/your-username/openproject-mcp-server.git
cd openproject-mcp-server

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Build for production
bun run build

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.