Status: Work in progress (WIP). Contributions are welcome while the tool surface and integration story stabilise.

OpenProject MCP Server

A Model Context Protocol (MCP) server that gives AI assistants high-fidelity access to OpenProject API v3. The server exposes curated tools for project discovery, work package collaboration, time tracking, attachments, wiki content, and user resolution—all through a fast asynchronous Python stack optimised for LLM workflows.

Table of Contents

• Overview

• Architecture at a Glance

• Tool Catalog

• Repository Layout

• Quickstart

• Configuration

• Running the Server

• Working With MCP Clients

• Testing & Quality

• Troubleshooting

• Known Limitations & Roadmap

• Contributing

• License

Related MCP server: Tonle OpenProject MCP Server

Overview

• Purpose-built for MCP: Ships with a FastMCP implementation that can be dropped into Claude Desktop, Cursor, modelcontextclient, or any other MCP host.

• Async & resilient: Uses httpx with request retries, exponential backoff, timeout tuning, and sanitised error handling.

• Rich tool surface: LLMs can comment on work packages, search across content, manage attachments, resolve users, log time, and query wiki pages.

• Typed contracts: Pydantic models validate every tool input to protect the OpenProject API from malformed prompts.

• Pyproject-only tooling: uv drives dependency management, ensuring reproducible environments and quick install times.

Architecture at a Glance

Tool Catalog

Each tool is exposed via the MCP protocol—LLMs call them exactly as defined here.

System

• system_ping: Quick readiness check (returns {"ok": true}) to let MCP clients validate connectivity.

Work Packages (src/openproject_mcp/tools/work_packages.py)

• add_comment: Post Markdown comments with optional watcher notifications.

• search_content: Search work packages and/or projects, optionally capturing attachment matches.

• append_work_package_description: Append Markdown to an existing description while handling optimistic locking.

• get_work_package_statuses: List all statuses available to the authenticated user.

• get_work_package_types: List every type globally or scoped to a project.

• resolve_status: Turn a human status name into an ID/disambiguation payload.

• resolve_type: Resolve a type name inside a project, including fallback when the type exists but is disabled there.

Attachments (src/openproject_mcp/tools/attachments.py)

• attach_file_to_wp: Upload local files to work packages via multipart/form-data.

• list_attachments: Enumerate attachments on a work package.

• download_attachment: Download binary content (optionally persisting to disk) with base64 responses for in-memory use.

• get_attachment_content: Fetch metadata plus a preview slice using HTTP range requests to save bandwidth.

Projects (src/openproject_mcp/tools/projects.py)

• get_project_memberships: Fetch project member/role mappings with pagination and multi-page follow mode.

• resolve_project: Resolve names/identifiers with disambiguation hints so LLMs can pick the right project.

Queries (src/openproject_mcp/tools/queries.py)

• list_queries: List saved queries (global or project-scoped).

• run_query: Execute saved queries and support prompt-time filter overrides.

Time Entries (src/openproject_mcp/tools/time_entries.py)

• list_time_entries: Filter by project, work package, user, and date span using native OpenProject operators.

• log_time: Convert decimal hours to ISO-8601 durations and create time entries (including optional user, activity, and timestamps).

Users (src/openproject_mcp/tools/users.py)

• resolve_user: Search active principals by name.

• get_user_by_id: Retrieve a single user with full metadata.

Wiki (src/openproject_mcp/tools/wiki.py)

• get_wiki_page: Retrieve wiki metadata, versions, and cross-links.

• attach_file_to_wiki: Upload files to wiki pages.

• list_wiki_page_attachments: List attachments on a wiki page.

Repository Layout

├── src/openproject_mcp
│   ├── main.py            # CLI entry point (stdio server)
│   ├── server.py          # FastMCP factory + tool registration
│   ├── config.py          # Pydantic settings (env-driven)
│   ├── client.py          # Resilient httpx/OpenProject client
│   ├── errors.py          # Domain-specific exceptions and sanitisation
│   ├── utils/logging.py   # Log configuration helper
│   └── tools/             # Tool families grouped by domain
├── tests/                 # Async pytest suite and smoke tests
├── pyproject.toml         # uv/PEP 621 metadata + tooling config
├── uv.lock                # Locked dependency graph
├── requirements.txt       # Convenience export (mirrors pyproject deps)
└── env_example.txt        # Template for `.env`

Quickstart

1. Install prerequisites

   • Python 3.10+

   • uv for blazing-fast installs (curl -LsSf https://astral.sh/uv/install.sh | sh)

   • Access to an OpenProject instance and a personal API token

2. Clone the repository

   git clone https://github.com/your-org/openproject-mcp-ai-integration.git
   cd openproject-mcp-ai-integration

3. Install dependencies

   uv sync  # creates .venv and installs runtime + dev deps

4. Configure environment

   cp env_example.txt .env
   # edit .env with your OpenProject URL + API token

5. Run a smoke test

   uv run python -m openproject_mcp.main  # prints nothing and blocks while serving stdio

   Stop with Ctrl+C once you confirm the server boots without configuration errors.

Configuration

openproject_mcp.config.Settings consumes the following environment variables (case-insensitive thanks to Pydantic). Assign them in .env or via your MCP client configuration.

Additional keys in env_example.txt (OPENPROJECT_PROXY, TEST_CONNECTION_ON_STARTUP) are placeholders for future enhancements and are currently ignored.

Running the Server

The project exposes a console script named openproj-mcp (configured in pyproject.toml). Run it through uv to ensure dependencies are resolved via the project virtual environment:

uv run openproj-mcp

• The process blocks and communicates over stdio per MCP specification.

• Use LOG_LEVEL=DEBUG to surface HTTP requests/responses during debugging.

• Health-check via system_ping from your MCP client before invoking other tools.

Working With MCP Clients

Claude Desktop (macOS & Windows)

Add an entry to claude_desktop_config.json:

{
  "mcpServers": {
    "openproject": {
      "command": "uv",
      "args": ["run", "openproj-mcp"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "sk_...",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Restart Claude Desktop and confirm the server appears in the MCP tool list. Other MCP hosts (Cursor, Continue, etc.) follow the same pattern: point to uv run openproj-mcp and provide the environment through their configuration UI.

Testing & Quality

The repo includes async-first tests plus static analysis hooks.

Helpful docs live in tests/TESTING_CHECKLIST.md (e.g., the checklist for add_comment).

Troubleshooting

Set LOG_LEVEL=DEBUG to trace HTTP calls. The server mutes noisy httpx logs when running at higher log levels.

Known Limitations & Roadmap

• Proxy configuration and startup connectivity tests are stubbed in .env_example but not implemented.

• Time entry activities must be referenced by ID (e.g., check OpenProject → Administration → Time tracking). A dedicated lookup tool is planned.

• There is no high-level permission inspection yet; use OpenProject’s UI to confirm rights if you receive 403 errors.

• Only stdio transport is provided today. Socket or HTTP transports would require additional glue around FastMCP.

• The tool surface focuses on read/write operations tested in tests/. If you need new API coverage (e.g., versions, relations), PRs are welcome.

Contributing

1. Fork & clone the repo.

2. Create a feature branch: git checkout -b feature/<topic>.

3. Run uv run ruff check, uv run black, uv run mypy, and uv run pytest before committing.

4. Submit a PR describing the motivation, testing performed, and any OpenProject prerequisites.

Please avoid committing secrets—.env is gitignored, and errors.py scrubs sensitive tokens from exception text.

Credits & Origins

This codebase was originally forked from the openproject-mcp-server project by AndyEverything (MIT-licensed). Under Oleksandr Pometun's maintenance it has since been heavily refactored into a distinct implementation with a different architecture, tooling setup, and feature scope aimed at a production-ready MCP server and portfolio reference.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

• Inspired by the Model Context Protocol community work.

• Integrates with OpenProject API v3.