MCP Server: OpenProject, GitHub, Claude & Windsurf

Overview

This MCP (Model Context Protocol) server integrates OpenProject with a GitHub App installation and exposes a small set of developer-friendly tools and adapters so multiple AI assistants (for example Claude Code and Windsurf) can operate over project context. The server collects context from OpenProject work packages and GitHub repositories, normalizes it into the MCP format, and forwards it to configured language-model assistants or responders. This makes it easier to add AI-powered workflows—issue summarization, code-aware suggestions, changelog generation, cross-system linking—without building custom integrations for each model.

The project is intended for developers who want a lightweight bridge between project management data (OpenProject), GitHub installations, and AI assistants. It ships with a local CLI, connector adapters, and configuration-driven assistant mappings so teams can iterate quickly and evaluate different models or assistants for automation tasks.

Features

• Adapters for OpenProject (work packages, attachments) and GitHub App installation (issues, PRs, commits)
• Support for multiple AI assistants (example adapters: Claude Code, Windsurf)
• CLI tooling for local testing, context inspection, and running single-shot prompts
• Docker Compose and Node-based server for quick deployment
• Config-driven assistant mapping and prompt templates
• Webhook receiver for GitHub events to keep context fresh
• Simple MCP format for exchanging context between connectors and assistants

Installation / Configuration

Prerequisites: Docker (or Node 16+), an OpenProject instance, a GitHub App, and API keys for any assistants you plan to use.

1. Clone the repository:

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

2. Copy example environment and edit values:

cp .env.example .env
# Edit .env to include your values

Example .env variables (summarized):

3. Run with Docker Compose (recommended for quick start):

docker compose up --build

Or install node dependencies and run locally:

npm install
npm run build
npm start

4. Configure GitHub webhooks to point at:

https://<your-host>/webhook/github

and ensure your OpenProject credentials are valid for the configured user.

Example assistant mapping (mcp.config.yml)

assistants:
  claude-code:
    type: claude
    api_key_env: CLAUDE_API_KEY
    max_tokens: 2000
  windsurf:
    type: windsurf
    api_key_env: WINDSURF_API_KEY
connectors:
  openproject:
    enabled: true
  github:
    enabled: true

Available Tools / Resources

• CLI: local “mcp” commands for testing and inspection
  • mcp context: fetch and show MCP context from a work package or repo
  • mcp run –assistant= –prompt=“…” : run a single prompt against an assistant using collected context
  • HTTP API:
    • POST /mcp/run — submit a MCP request and receive assistant response
    • POST /webhook/github — GitHub webhook endpoint
  • Sample prompt templates and response format examples in the repo’s /templates folder
  • Example Postman collection and cURL snippets for quick integration testing

  Use Cases

  • Sync GitHub issues to OpenProject work packages and generate human-readable summaries

    • When a new GitHub issue opens, the webhook triggers the MCP server to assemble context (recent commits, related PRs, OpenProject project metadata) and asks an assistant to produce a short summary for the work package description.

  • Generate code-aware suggestions using Claude Code

    • A developer requests “Refactor function X in repo Y” via the CLI. The server gathers file snippets and commit history, sends it to Claude Code, and returns patch suggestions or high-level refactor steps.

  • Automated PR description and changelog drafts

    • On PR creation, the MCP server prompts an assistant (e.g., Windsurf) with impacted files and issue references, receiving a draft PR description and suggested changelog entries to attach to the PR or OpenProject release note.

  • Cross-system Q&A chatbot for project managers

    • Use the MCP API to power a chat UI that answers “What’s blocking release 1.2?” by aggregating OpenProject blocking work packages, related GitHub PR statuses, and recent CI commit outcomes.

  Where to find the code

  Source and issues: https://github.com/boma086/mcp-openproject

  For contributors: check the CONTRIBUTING.md and the example configurations in the repo to add new assistant adapters or extend connectors.

  Tags:developer-tools