# OpenProject

Connects your OpenProject instance to your coding agent via API v3. Handles work packages and project summaries inside the chat.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: kar-thik
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/kar-thik/openproject-mcp
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/mcp/openproject

## What it does

This server connects coding assistants to the OpenProject API v3 through 91 tools. The model can inspect open tasks and update statuses directly. Every response uses typed schemas. As a result, the assistant receives structured data instead of unstructured text.

The setup targets self-hosted Community editions lacking native assistant integrations. It works against any deployment from 14 LTS through 17.x. It runs on FastMCP and httpx over HTTP/2. Without Python 3.12 and an active API token, startup halts immediately with exit code 2 rather than printing a raw crash dump.

Destructive operations require explicit confirmation arguments to prevent accidental changes. You can also activate a read-only mode. Project membership edits remain gated behind administrator permissions.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `OPENPROJECT_URL`, `OPENPROJECT_API_KEY`, `OPENPROJECT_OAUTH_TOKEN`, `OPENPROJECT_MCP_READ_ONLY`, `OPENPROJECT_MCP_ADMIN_TOOLS`, `OPENPROJECT_MCP_DISABLE`, `OPENPROJECT_MCP_PROFILE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env OPENPROJECT_URL=<OPENPROJECT_URL> --env OPENPROJECT_API_KEY=<OPENPROJECT_API_KEY> --env OPENPROJECT_OAUTH_TOKEN=<OPENPROJECT_OAUTH_TOKEN> --env OPENPROJECT_MCP_READ_ONLY=<OPENPROJECT_MCP_READ_ONLY> --env OPENPROJECT_MCP_ADMIN_TOOLS=<OPENPROJECT_MCP_ADMIN_TOOLS> --transport stdio openproject -- uvx openproject-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from openproject-mcp-server <command>

### Codex

**Platform CLI**
```bash
codex mcp add openproject --env OPENPROJECT_URL=<OPENPROJECT_URL> --env OPENPROJECT_API_KEY=<OPENPROJECT_API_KEY> --env OPENPROJECT_OAUTH_TOKEN=<OPENPROJECT_OAUTH_TOKEN> --env OPENPROJECT_MCP_READ_ONLY=<OPENPROJECT_MCP_READ_ONLY> --env OPENPROJECT_MCP_ADMIN_TOOLS=<OPENPROJECT_MCP_ADMIN_TOOLS> -- uvx openproject-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from openproject-mcp-server <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "openproject": {
            "command": "uvx",
            "args": [
                "openproject-mcp-server"
            ],
            "env": {
                "OPENPROJECT_URL": "<OPENPROJECT_URL>",
                "OPENPROJECT_API_KEY": "<OPENPROJECT_API_KEY>",
                "OPENPROJECT_OAUTH_TOKEN": "<OPENPROJECT_OAUTH_TOKEN>",
                "OPENPROJECT_MCP_READ_ONLY": "<OPENPROJECT_MCP_READ_ONLY>",
                "OPENPROJECT_MCP_ADMIN_TOOLS": "<OPENPROJECT_MCP_ADMIN_TOOLS>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from openproject-mcp-server <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "openproject": {
            "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>",
                "OPENPROJECT_MCP_READ_ONLY": "<OPENPROJECT_MCP_READ_ONLY>",
                "OPENPROJECT_MCP_ADMIN_TOOLS": "<OPENPROJECT_MCP_ADMIN_TOOLS>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from openproject-mcp-server <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e OPENPROJECT_URL=<OPENPROJECT_URL> -e OPENPROJECT_API_KEY=<OPENPROJECT_API_KEY> -e OPENPROJECT_OAUTH_TOKEN=<OPENPROJECT_OAUTH_TOKEN> -e OPENPROJECT_MCP_READ_ONLY=<OPENPROJECT_MCP_READ_ONLY> -e OPENPROJECT_MCP_ADMIN_TOOLS=<OPENPROJECT_MCP_ADMIN_TOOLS> openproject uvx openproject-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from openproject-mcp-server <command>

## When to use it
- inspect overdue work packages and update priorities
- generate agile sprint summaries and progress overviews
- log working hours against active assignments
- post updates and notes to task discussion threads

## Example prompts
- List open work packages in website-relaunch due before Friday.
- Set priority to High on issue #4821 and add a comment for the assignee.
- Generate a weekly agile report for project website-relaunch.

## Similar
- [Reactive Resume](https://affpapa.org/en/nevibecode/mcp/reactive-resume.md) — MCP server · ★ 44908
- [screenpipe](https://affpapa.org/en/nevibecode/mcp/screenpipe.md) — MCP server · ★ 22082
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12826
- [kaneo](https://affpapa.org/en/nevibecode/mcp/kaneo.md) — MCP server · ★ 9623
- [Mindwtr](https://affpapa.org/en/nevibecode/mcp/mindwtr.md) — MCP server · ★ 2330
- [Azure DevOps (ADO)](https://affpapa.org/en/nevibecode/mcp/azure-devops-ado.md) — MCP server · ★ 2071

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md