OpenProject MCP Server

An MCP (Model Context Protocol) server for OpenProject, built with FastMCP. Enables AI assistants like Claude to interact with OpenProject — listing projects, work packages, and managing resources through natural language.

Architecture

This project follows a Thin Client + Separate Tools architecture with clear separation of concerns:

AI Agent → MCP Client → FastMCP Server → Tool Functions → OpenProject API
                                        ↓
                                   Logfire (traces, metrics)

Design Patterns

Pattern	Where	Purpose
Singleton	src/config/settings.py	Single settings instance via get_settings()
Factory Method	src/factories/client_factory.py	Centralizes client creation
Abstract Base Class	src/client/base.py	Thin contract for client implementations
Dependency Injection	OpenProjectClient(settings)	Settings passed in, not imported globally

Project Structure

src/
├── api/
│   ├── middleware.py          # Auth middleware (API key verification)
│   └── mcp_server.py         # FastMCP server with lifespan & tool registration
├── client/
│   ├── base.py               # ABC defining client interface
│   └── openproject.py        # Concrete client wrapping httpx.AsyncClient
├── config/
│   └── settings.py           # Pydantic Settings with Singleton pattern
├── factories/
│   └── client_factory.py     # Factory for creating OpenProject clients
├── schema/
│   ├── project.py            # Project & Description Pydantic models
│   └── work_package.py       # WorkPackage & WorkPackageDescription models
└── tools/
    ├── list_project.py       # list_openproject_projects()
    └── list_work_packages.py # list_project_workpackages()

tests/
├── conftest.py               # Shared fixtures & mock helpers
├── test_schemas.py           # Pydantic model validation tests
├── test_settings.py          # Settings singleton tests
├── client/
│   └── test_openproject.py   # Client configuration tests
└── tools/
    └── test_list_projects.py # Tool function tests with mocked HTTP

Setup

1. Clone and Install

git clone <repository-url>
cd "OpenProject MCP"
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env

Edit .env with your values:

# OpenProject API Configuration
OPENPROJECT_TOKEN=your_openproject_api_token_here
OPENPROJECT_APIROOT=http://localhost:8080

# MCP Server Authentication
MCP_SERVER_API=your_api_key_here

# Logfire Observability
LOGFIRE_TOKEN=your_logfire_write_token_here

3. Get OpenProject API Token

1. Log in to your OpenProject instance
2. Go to My Account → API token
3. Generate a new token
4. Copy it to OPENPROJECT_TOKEN in .env

Usage

Start the Server (HTTP Transport)

python -m src.api.mcp_server

Server runs on http://127.0.0.1:8000/mcp

Test with MCP Inspector

# List available tools
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --transport http --method tools/list

# Call a tool
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --transport http --method tools/call --tool-name list_projects

Test with curl

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_projects"}, "id": 1}'

Available Tools

Tool	Description	Parameters
list_projects	List all projects in OpenProject	—
list_workpackages	List work packages for a project	project_id (required)

Authentication

The server supports API key authentication via HTTP headers:

-H "x-api-key: your_api_key_here"

In stdio mode (used by Claude Desktop), authentication is skipped automatically.

Observability (Logfire)

This server uses Pydantic Logfire for observability, providing:

• MCP tool call tracing — who called which tool, duration, result
• HTTP request monitoring — all OpenProject API calls tracked
• Error tracking — full stack traces for debugging
• Real-time dashboard — visualize traces at https://logfire.pydantic.dev

Setup

1. Create a Logfire account at https://logfire.pydantic.dev
2. Go to Settings → API Keys → Create a Write Token
3. Add LOGFIRE_TOKEN=your_token_here to your .env file

What Gets Traced

Trace Type	What It Shows
MCP Tool Calls	list_projects, list_workpackages — caller, duration, result
HTTP Requests	GET /api/v3/projects — status code, latency, errors
Errors	Any exceptions with full stack traces
Lifespan	Server startup/shutdown events

Testing

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_schemas.py

Test Coverage

• Schema tests: Pydantic model validation, field aliases, optional fields
• Settings tests: Singleton pattern, environment variables, missing fields
• Client tests: HTTP client configuration, auth setup, lifecycle
• Tool tests: API calls, response parsing, error handling

Design Decisions

Why Thin Client + Separate Tools?

The client (OpenProjectClient) only handles HTTP connectivity. Tool functions (list_openproject_projects, etc.) own the business logic. This follows the Single Responsibility Principle and makes extending tools straightforward — add a new function, not modify existing code.

Why Raw _links Dict?

WorkPackage uses links: dict = Field(alias="_links") instead of a model_validator. This keeps the model simple while preserving all link data. Tool functions extract nested fields as needed.

TODO

• [ ] Add more tools: get_project, get_work_package, create_work_package
• [ ] Implement role-based permission system (read-only vs admin tools)
• [ ] Strategy pattern for auth methods (API key, OAuth, BasicAuth)
• [ ] Add User management tools (list_users, create_user, delete_user)

Requirements

• Python 3.12+
• OpenProject instance with API access

Dependencies

• fastmcp — MCP server framework
• httpx — Async HTTP client
• pydantic — Data validation
• pydantic-settings — Environment-based configuration
• logfire — Observability and tracing
• pytest / pytest-asyncio — Testing