Skip to content
MCP server

OpenProject

91 tools for OpenProject API v3 with read-only mode, admin gate and tool-group switches

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.5.0
Listing updated
2 days ago

About OpenProject

OpenProject is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.

This server targets self-hosted OpenProject Community instances, filling the gap left by the Enterprise edition's own built-in MCP integration, though it works against any edition that exposes API v3. It covers OpenProject 14 LTS through 17.x, and adapts to version differences by probing features lazily instead of assuming them.

The tools span work packages, comments and relations, attachments, git and pull-request activity, projects, saved queries, notifications, time tracking, versions, people and memberships, meetings, news, documents, budgets and reporting, plus four report prompts and three resource templates. Every tool returns a typed model with an output schema, and errors come back as a JSON envelope with a type, the HTTP status, a message and a hint for fixing the call. When a module is missing, a tool returns an empty page with an explanation instead of a fake success.

Safety switches include read-only mode, admin-gated membership writes, per-group disabling, a core or full profile and a confirm flag on destructive tools. Configuration is an instance URL plus an API key from My account, Access tokens; an OAuth bearer token can replace the key. Python 3.12 or newer is required.

Install

Run in a terminal

claude mcp add openproject-mcp-server --env OPENPROJECT_URL='<OPENPROJECT_URL>' --env OPENPROJECT_API_KEY='<OPENPROJECT_API_KEY>' --env OPENPROJECT_OAUTH_TOKEN='<OPENPROJECT_OAUTH_TOKEN>' -- uvx openproject-mcp-server

Add to claude_desktop_config.json

{
  "mcpServers": {
    "openproject-mcp-server": {
      "command": "uvx",
      "args": [
        "openproject-mcp-server"
      ],
      "env": {
        "OPENPROJECT_URL": "<OPENPROJECT_URL>",
        "OPENPROJECT_API_KEY": "<OPENPROJECT_API_KEY>",
        "OPENPROJECT_OAUTH_TOKEN": "<OPENPROJECT_OAUTH_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "openproject-mcp-server": {
      "command": "uvx",
      "args": [
        "openproject-mcp-server"
      ],
      "env": {
        "OPENPROJECT_URL": "<OPENPROJECT_URL>",
        "OPENPROJECT_API_KEY": "<OPENPROJECT_API_KEY>",
        "OPENPROJECT_OAUTH_TOKEN": "<OPENPROJECT_OAUTH_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "openproject-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "openproject-mcp-server"
      ],
      "env": {
        "OPENPROJECT_URL": "<OPENPROJECT_URL>",
        "OPENPROJECT_API_KEY": "<OPENPROJECT_API_KEY>",
        "OPENPROJECT_OAUTH_TOKEN": "<OPENPROJECT_OAUTH_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "openproject-mcp-server": {
      "command": "uvx",
      "args": [
        "openproject-mcp-server"
      ],
      "env": {
        "OPENPROJECT_URL": "<OPENPROJECT_URL>",
        "OPENPROJECT_API_KEY": "<OPENPROJECT_API_KEY>",
        "OPENPROJECT_OAUTH_TOKEN": "<OPENPROJECT_OAUTH_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "openproject-mcp-server": {
      "command": "uvx",
      "args": [
        "openproject-mcp-server"
      ],
      "env": {
        "OPENPROJECT_URL": "<OPENPROJECT_URL>",
        "OPENPROJECT_API_KEY": "<OPENPROJECT_API_KEY>",
        "OPENPROJECT_OAUTH_TOKEN": "<OPENPROJECT_OAUTH_TOKEN>"
      }
    }
  }
}

Configuration

  • OPENPROJECT_URLOpenProject instance root URL, e.g. https://openproject.example.comRequired
  • OPENPROJECT_API_KEYAPI key from My account -> Access tokens in OpenProjectRequired
  • OPENPROJECT_OAUTH_TOKENOAuth bearer token used instead of the API key (OAuth deployments)
  • OPENPROJECT_MCP_READ_ONLYSet to 1 to serve read tools only
  • OPENPROJECT_MCP_ADMIN_TOOLSSet to 1 to enable the membership-write tools (hidden by default)
  • OPENPROJECT_MCP_DISABLEComma-separated tool groups to drop, e.g. meetings,budgets
  • OPENPROJECT_MCP_PROFILEcore (default) or full: core hides the module-backed tool groups at startup

Tools this server provides (4)

Taken from the project documentation; the running server may differ.

list_work_packages
List work packages with filters and sorting.
update_work_package
Update fields such as priority on a work package.
add_work_package_comment
Add a comment to a work package.
get_instance_info
Live end-to-end check of the connected instance.

What it does

91 OpenProject tools
Covers work packages, projects, time tracking, meetings, budgets and more.
Typed results and hints
Structured output with error envelopes that say how to fix the call.
Read-only mode
One setting serves read tools only.
Admin gate and groups
Membership writes are hidden by default and tool groups can be dropped.
Version-adaptive
Probes API differences across OpenProject 14 LTS to 17.x.
Report prompts
Prompt templates return finished weekly reports from live data.

Good for

  • List open work packages due this week and raise an urgent bug
  • Log a comment on a work package for its owner
  • Generate a weekly project report from live data
  • Check what a self-hosted instance supports

Pricing

Open source

Free; open source

OpenProject FAQ

Which OpenProject versions work?

14 LTS through 17.x, any edition, though it is aimed at Community.

What credentials does it need?

The instance URL and an API key from My account, Access tokens; OAuth bearer tokens are supported as an alternative.

Can I stop it from writing?

Yes, set OPENPROJECT_MCP_READ_ONLY to 1.

What Python version is required?

Python 3.12 or newer.

Is OpenProject free?

Yes. OpenProject is open source, so you can use and self-host it for free.

How do I add OpenProject to Claude Code?

Run this command in your terminal: claude mcp add openproject-mcp-server --env OPENPROJECT_URL='<OPENPROJECT_URL>' --env OPENPROJECT_API_KEY='<OPENPROJECT_API_KEY>' --env OPENPROJECT_OAUTH_TOKEN='<OPENPROJECT_OAUTH_TOKEN>' -- uvx openproject-mcp-server

What are the best alternatives to OpenProject?

The closest alternatives to OpenProject are Ha MCP, Concord MCP, note1, CalderFlow and nicemails.

Alternatives to OpenProject

  1. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  2. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools
  3. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  4. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media
  5. nicemails

    MCP server

    Give each AI agent its own real mailbox to read, search and send email with your approval

    • 8 tools
    • Remote
    • Freemium
    • Communication
  6. Transcribe audio and video links from Claude or ChatGPT and read the results

    Not checked yet
    • 5 tools
    • Remote
    • Freemium
    • Design and media