OpenProject — Claude Code MCP server: what it does, how to install
Connects your OpenProject instance to your coding agent via API v3. Handles work packages and project summaries inside the chat.
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-serverWhat OpenProject 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.
What it helps with
- 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 for the agent
- 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.
How to install OpenProject
Platform CLI
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-serverReplace <…> 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>
Platform CLI
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-serverReplace <…> 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>
Config file
{
"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>
Config file
{
"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>
Platform CLI
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-serverReplace <…> 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>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about OpenProject
How to install OpenProject in Claude Code?
Run `claude mcp add openproject-mcp-server -e OPENPROJECT_URL=<OPENPROJECT_URL> -e OPENPROJECT_API_KEY=<OPENPROJECT_API_KEY> -e OPENPROJECT_OAUTH_TOKEN=<OPENPROJECT_OAUTH_TOKEN> -- uvx openproject-mcp-server`.
What does the OpenProject MCP server do?
It connects your coding agent to OpenProject API v3, exposing tools for work packages, time logs, and status reports.
Which OpenProject versions are supported?
It supports OpenProject 14 LTS through 17.x and requires Python 3.12 or newer alongside an API token.
