openproject-mcp is a Model Context Protocol (MCP) server that connects AI assistants (such as Claude Desktop, Cursor, and Antigravity) to OpenProject via OpenProject's REST API v3.

It allows agents to browse, query, and reason about OpenProject workspaces using personal API keys over standard MCP transports (stdio).

Features

Project Discovery: List accessible projects, inspect hierarchies, and retrieve project details.
Work Package Browsing: Query work packages with status, type, assignee, priority, and custom filters; inspect work package details and parent/child relationships.
Saved Queries (Views): Discover and execute saved project and global queries.
Taxonomies & Metadata: Query work package types (Tasks, Bugs, Features), statuses, priorities, and users to enable structured agent reasoning.
OpenAPI Schema Introspection: Query dynamic endpoint specifications, parameter schemas, and data models directly from the connected OpenProject instance with in-memory caching.
HAL+JSON Normalization: Converts OpenProject's verbose HAL+JSON representations into concise, token-efficient structures.
Secure Authentication: Uses OpenProject Personal API tokens via HTTP Basic Auth (apikey:<token>) with zero credential storage inside the codebase.
Multi-Platform Docker Images: Official multi-architecture images (linux/amd64 and linux/arm64) published to GitHub Container Registry (ghcr.io).

Project Documentation

AGENTS.md: Guidelines, coding standards, and workflow instructions for AI coding agents.
docs/ARCHITECTURE.md: System architecture, layer diagrams, tool schemas, and technical design.
docs/DECISIONS.md: Architectural Decision Records (ADRs) documenting stack choices, protocols, and designs.
docs/TODO.md: Task tracking, roadmap, and agent check-in policies.

Obtaining an OpenProject API Token

To connect openproject-mcp to your OpenProject instance, generate a personal API token:

Log in to your OpenProject web interface.
In the top-right corner, click on your user avatar and select My account.
In the left navigation menu, click on Access tokens.
In the API row, click Generate (or Reset if an existing token was lost).
Copy the generated API token (it starts with opapi_ or similar hex/alphanumeric string).
Keep this token safe; you will pass it via OPENPROJECT_API_KEY.

Running openproject-mcp

You can run openproject-mcp using either Docker (no local dependencies required) or Bun (local development).

Method 1: Docker (Recommended)

Official multi-architecture container images are published to GitHub Container Registry (ghcr.io).

Interactive Execution

docker run -i --rm \
  -e OPENPROJECT_BASE_URL="https://openproject.example.com" \
  -e OPENPROJECT_API_KEY="your-api-key" \
  ghcr.io/stereotypicalcat/openproject-mcp:latest

Read-Only Mode

To strictly restrict capabilities to read-only browsing:

docker run -i --rm \
  -e OPENPROJECT_BASE_URL="https://openproject.example.com" \
  -e OPENPROJECT_API_KEY="your-api-key" \
  ghcr.io/stereotypicalcat/openproject-mcp:latest --read-only

(Alternatively, pass -e OPENPROJECT_READ_ONLY=true.)

Method 2: Local Execution with Bun

If you prefer to run from source:

Install Bun (>= 1.2 / 1.3):

curl -fsSL https://bun.sh/install | bash

Clone and install dependencies:

git clone https://github.com/StereotypicalCat/openproject-mcp.git
cd openproject-mcp
bun install

Run the server:

OPENPROJECT_BASE_URL="https://openproject.example.com" \
OPENPROJECT_API_KEY="your-api-key" \
bun run src/index.ts

For read-only mode:

OPENPROJECT_BASE_URL="https://openproject.example.com" \
OPENPROJECT_API_KEY="your-api-key" \
bun run src/index.ts --read-only

MCP Client Configuration

Claude Desktop

Edit your claude_desktop_config.json:

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

Option A: Docker (Zero Installation)

{
  "mcpServers": {
    "openproject": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "OPENPROJECT_BASE_URL=https://openproject.example.com",
        "-e", "OPENPROJECT_API_KEY=your-api-key",
        "ghcr.io/stereotypicalcat/openproject-mcp:latest",
        "--read-only"
      ]
    }
  }
}

Option B: Bun (From Source)

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/openproject-mcp/src/index.ts",
        "--read-only"
      ],
      "env": {
        "OPENPROJECT_BASE_URL": "https://openproject.example.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Add the configuration in .cursor/mcp.json (or under Cursor Settings > Features > MCP):

Docker Configuration

{
  "mcpServers": {
    "openproject": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "OPENPROJECT_BASE_URL=https://openproject.example.com",
        "-e", "OPENPROJECT_API_KEY=your-api-key",
        "ghcr.io/stereotypicalcat/openproject-mcp:latest",
        "--read-only"
      ]
    }
  }
}

Bun Configuration

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": [
        "run",
        "/absolute/path/to/openproject-mcp/src/index.ts",
        "--read-only"
      ],
      "env": {
        "OPENPROJECT_BASE_URL": "https://openproject.example.com",
        "OPENPROJECT_API_KEY": "your-api-key"
      }
    }
  }
}

Interactive Testing with MCP Inspector

You can visually test and debug tool calls, explore parameter schemas, and inspect raw JSON payloads using the official MCP Inspector:

# Using Bun directly
OPENPROJECT_BASE_URL="http://localhost:8080" \
OPENPROJECT_API_KEY="your-api-key" \
bunx @modelcontextprotocol/inspector bun run src/index.ts

Or test the published Docker image:

bunx @modelcontextprotocol/inspector docker run -i --rm \
  -e OPENPROJECT_BASE_URL="http://localhost:8080" \
  -e OPENPROJECT_API_KEY="your-api-key" \
  ghcr.io/stereotypicalcat/openproject-mcp:latest

This launches a local web UI (typically at http://localhost:5173) where you can trigger tools and review formatted outputs.

Available MCP Tools

openproject-mcp currently exposes 11 tools:

Projects

openproject_list_projects: List projects with pagination (offset, pageSize), sorting (sortBy), and filtering.
openproject_get_project: Retrieve project details and metadata by ID or identifier (e.g. projectId: "mcp-test-project" or projectId: 4).

Work Packages

openproject_list_work_packages: Query work packages with high-level filters (projectId, status, typeId, assigneeId, priorityId, subject, pageSize, offset) or custom JSON filter expressions.
openproject_get_work_package: Retrieve detailed information for a specific work package by ID (workPackageId: 38), including description, type, status, priority, author, dates, parent, and children.

Saved Queries & Views

openproject_list_queries: List saved queries/views accessible to the authenticated user, optionally scoped to a project.
openproject_get_query: Retrieve saved query configuration and the work packages returned by that query (queryId: 30).

Taxonomies & Metadata

openproject_list_types: List all work package types (e.g., Task, Bug, Feature, Milestone), optionally scoped to a project.
openproject_list_statuses: List all configured work package statuses (e.g., New, In progress, Closed) and their closed flags.
openproject_list_priorities: List all configured priority levels (e.g., Low, Normal, High, Immediate).
openproject_list_users: List users in the OpenProject instance with pagination and status filtering.

OpenAPI Introspection

openproject_get_openapi_spec: Inspect OpenProject REST API v3 documentation dynamically with in-memory caching.
- Default / summary: true: Returns compact summary of available tags, paths, and usage instructions.
- path: "/api/v3/work_packages": Returns parameter and operation schemas for a specific endpoint.
- tag: "Work Packages": Returns all endpoints grouped under a tag.
- schema: "WorkPackageModel": Returns the JSON Schema definition for a component model.

Example Prompts for AI Assistants

Once connected in Claude Desktop, Cursor, or your agent of choice, you can ask queries such as:

"List all projects in OpenProject and tell me which ones are active."
"Show me all open bugs in the 'mcp-test-project' project."
"What work packages are assigned to me, and what are their priorities?"
"Get details for work package #38 including its child tasks."
"Show the saved queries available for project 4 and run 'MCP Active Tasks'."
"What work package types and statuses are available in our OpenProject instance?"
"Inspect the OpenAPI schema for creating work packages using openproject_get_openapi_spec."

Quickstart: Local OpenProject Test Stack

A complete OpenProject 17 environment with PostgreSQL 17 and Memcached is included via Docker Compose for local testing and agentic validation.

Prerequisites

Docker and Docker Compose (v2+)
Bun (>= 1.2 / 1.3)

1. Start the Environment & Seed Data

Run the start script to boot the containers, wait for health checks, seed sample data, and generate a personal API token:

./scripts/start.sh

Or step-by-step:

# 1. Start the Docker Compose stack in the background
docker compose up -d

# 2. Wait for health checks, seed test data, and generate credentials
./scripts/seed.sh

This will automatically create .env.test and .env.local containing the generated credentials:

OPENPROJECT_BASE_URL=http://localhost:8080
OPENPROJECT_API_KEY=opapi-...
OPENPROJECT_TEST_PROJECT=mcp-test-project

2. Verify OpenProject is Running

Once seeded, OpenProject is accessible at http://localhost:8080:

Username: admin
Password: admin12345678

Verify the API v3 connection directly using curl:

curl -u "apikey:$(grep OPENPROJECT_API_KEY .env.test | cut -d= -f2)" \
  http://localhost:8080/api/v3/projects

3. Stop the Stack

./scripts/stop.sh
# or
docker compose down

To also remove database and asset volumes:

docker compose down -v

Configuration Reference

The MCP server accepts configuration through environment variables, CLI arguments, or a .env file:

Variable	Description	Default
`OPENPROJECT_BASE_URL`	Base URL of the OpenProject instance	`http://localhost:8080`
`OPENPROJECT_API_KEY`	Personal API token (created under My Account > Access tokens)	-
`OPENPROJECT_READ_ONLY`	Run server in read-only mode (`true` / `false` or `--read-only`)	`false`
`PORT`	Local port for the Docker Compose web container	`8080`
`TAG`	OpenProject container image tag	`17-slim`
`POSTGRES_VERSION`	PostgreSQL container image tag	`17`

Development

# Install dependencies
bun install

# Run type checker
bun run typecheck

# Run test suite
bun test

# Run MCP server locally over stdio
bun run src/index.ts

Development Roadmap

Phase 1 (Completed): Read-only browsing tools for projects, work packages, queries, taxonomies, and OpenAPI introspection.
Phase 2 (Upcoming): Mutating operations (create/update work packages, add comments, log time).
Phase 3: Attachment reading and document resources.
Phase 4: SSE / Stream transport for remote server deployments.

License

GNU General Public License v3.0 (aligned with OpenProject Community Edition).