244 lines
6.5 KiB
Markdown
244 lines
6.5 KiB
Markdown
# openproject-mcp
|
|
|
|
`openproject-mcp` is a Model Context Protocol (MCP) server that connects AI assistants (such as Claude Desktop, Cursor, and Antigravity) to [OpenProject](https://github.com/opf/openproject) via OpenProject's REST API v3.
|
|
|
|
It allows agents to browse, query, and reason about OpenProject workspaces using personal API keys over standard MCP transports (stdio).
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Project Discovery**: List accessible projects, inspect hierarchies, and retrieve project details.
|
|
- **Work Package Browsing**: Query work packages with status, type, and custom filters; inspect work package details and relationships.
|
|
- **Saved Queries (Views)**: Discover and execute saved project and global queries.
|
|
- **Taxonomies & Metadata**: Query work package types (Tasks, Bugs, Features), statuses, priorities, and users to enable structured agent reasoning.
|
|
- **HAL+JSON Normalization**: Converts OpenProject's verbose HAL+JSON representations into concise, token-efficient structures.
|
|
- **Secure Authentication**: Uses OpenProject Personal API tokens via HTTP Basic Auth (`apikey:<token>`) with zero credential storage inside the codebase.
|
|
|
|
---
|
|
|
|
## Project Documentation
|
|
|
|
- [AGENTS.md](AGENTS.md): Guidelines, coding standards, and workflow instructions for AI coding agents.
|
|
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): System architecture, layer diagrams, tool schemas, and technical design.
|
|
- [docs/DECISIONS.md](docs/DECISIONS.md): Architectural Decision Records (ADRs) documenting stack choices, protocols, and designs.
|
|
- [docs/TODO.md](docs/TODO.md): Task tracking, roadmap, and agent check-in policies.
|
|
|
|
---
|
|
|
|
## Running via Docker
|
|
|
|
You can run `openproject-mcp` without installing Bun or cloning this repository by using the container image published to GitHub Container Registry (`ghcr.io`).
|
|
|
|
### Docker Quickstart
|
|
|
|
Run interactively with standard I/O streaming:
|
|
|
|
```bash
|
|
docker run -i --rm \
|
|
-e OPENPROJECT_BASE_URL="https://openproject.example.com" \
|
|
-e OPENPROJECT_API_KEY="your-api-key" \
|
|
ghcr.io/stereotypicalcat/openproject-mcp:latest
|
|
```
|
|
|
|
### Read-Only Mode
|
|
|
|
To ensure the server strictly restricts capabilities to read-only queries and inspection:
|
|
|
|
```bash
|
|
docker run -i --rm \
|
|
-e OPENPROJECT_BASE_URL="https://openproject.example.com" \
|
|
-e OPENPROJECT_API_KEY="your-api-key" \
|
|
ghcr.io/stereotypicalcat/openproject-mcp:latest --read-only
|
|
```
|
|
|
|
*(Alternatively, pass `-e OPENPROJECT_READ_ONLY=true`.)*
|
|
|
|
### MCP Client Configuration
|
|
|
|
#### Claude Desktop
|
|
|
|
Add the following to your `claude_desktop_config.json`:
|
|
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"openproject": {
|
|
"command": "docker",
|
|
"args": [
|
|
"run",
|
|
"-i",
|
|
"--rm",
|
|
"-e",
|
|
"OPENPROJECT_BASE_URL=https://openproject.example.com",
|
|
"-e",
|
|
"OPENPROJECT_API_KEY=your-api-key",
|
|
"ghcr.io/stereotypicalcat/openproject-mcp:latest",
|
|
"--read-only"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Cursor
|
|
|
|
Add the following to `.cursor/mcp.json` (or Cursor Settings > Features > MCP):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"openproject": {
|
|
"command": "docker",
|
|
"args": [
|
|
"run",
|
|
"-i",
|
|
"--rm",
|
|
"-e",
|
|
"OPENPROJECT_BASE_URL=https://openproject.example.com",
|
|
"-e",
|
|
"OPENPROJECT_API_KEY=your-api-key",
|
|
"ghcr.io/stereotypicalcat/openproject-mcp:latest",
|
|
"--read-only"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Quickstart: Local OpenProject Test Stack
|
|
|
|
A complete OpenProject 17 environment with PostgreSQL 17 and Memcached is included via Docker Compose for local testing and agentic validation.
|
|
|
|
### Prerequisites
|
|
|
|
- Docker and Docker Compose (v2+)
|
|
- [Bun](https://bun.sh) (>= 1.2 / 1.3)
|
|
|
|
### 1. Start the Environment & Seed Data
|
|
|
|
Run the start script to boot the containers, wait for health checks, seed sample data, and generate a personal API token:
|
|
|
|
```bash
|
|
./scripts/start.sh
|
|
```
|
|
|
|
Or step-by-step:
|
|
|
|
```bash
|
|
# 1. Start the Docker Compose stack in the background
|
|
docker compose up -d
|
|
|
|
# 2. Wait for health checks, seed test data, and generate credentials
|
|
./scripts/seed.sh
|
|
```
|
|
|
|
This will automatically create `.env.test` and `.env.local` containing the generated credentials:
|
|
|
|
```env
|
|
OPENPROJECT_BASE_URL=http://localhost:8080
|
|
OPENPROJECT_API_KEY=opapi-...
|
|
OPENPROJECT_TEST_PROJECT=mcp-test-project
|
|
```
|
|
|
|
### 2. Verify OpenProject is Running
|
|
|
|
Once seeded, OpenProject is accessible at [http://localhost:8080](http://localhost:8080):
|
|
- **Username**: `admin`
|
|
- **Password**: `admin12345678`
|
|
|
|
You can verify the API v3 connection directly using `curl`:
|
|
|
|
```bash
|
|
curl -u "apikey:$(grep OPENPROJECT_API_KEY .env.test | cut -d= -f2)" \
|
|
http://localhost:8080/api/v3/projects
|
|
```
|
|
|
|
### 3. Stop the Stack
|
|
|
|
```bash
|
|
./scripts/stop.sh
|
|
# or
|
|
docker compose down
|
|
```
|
|
|
|
To also remove database and asset volumes:
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
---
|
|
|
|
## MCP Server Development (Bun)
|
|
|
|
Install project dependencies:
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
Start the MCP server over stdio:
|
|
|
|
```bash
|
|
bun run src/index.ts
|
|
```
|
|
|
|
Run test suite:
|
|
|
|
```bash
|
|
bun test
|
|
```
|
|
|
|
Type-check:
|
|
|
|
```bash
|
|
bun run typecheck
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
The MCP server accepts configuration through environment variables or a `.env` file:
|
|
|
|
| Variable | Description | Default |
|
|
| :--- | :--- | :--- |
|
|
| `OPENPROJECT_BASE_URL` | Base URL of the OpenProject instance | `http://localhost:8080` |
|
|
| `OPENPROJECT_API_KEY` | Personal API token (created under My Account > Access tokens) | - |
|
|
| `OPENPROJECT_READ_ONLY` | Run server in read-only mode (`true` / `false` or `--read-only`) | `false` |
|
|
| `PORT` | Local port for the Docker Compose web container | `8080` |
|
|
| `TAG` | OpenProject container image tag | `17-slim` |
|
|
| `POSTGRES_VERSION` | PostgreSQL container image tag | `17` |
|
|
|
|
### Read-Only Mode
|
|
|
|
To ensure AI assistants cannot make any modifications to your OpenProject instance, enable read-only mode:
|
|
|
|
```bash
|
|
OPENPROJECT_READ_ONLY=true bun run src/index.ts
|
|
# or
|
|
bun run src/index.ts --read-only
|
|
```
|
|
|
|
When active, write tools are omitted from the tool manifest and blocked by execution guards.
|
|
|
|
---
|
|
|
|
## Development Roadmap
|
|
|
|
- **Phase 1 (Current)**: Read-only browsing tools for projects, work packages, queries, and taxonomies.
|
|
- **Phase 2**: Mutating operations (create/update work packages, add comments, log time).
|
|
- **Phase 3**: Attachment reading and document resources.
|
|
- **Phase 4**: SSE / Stream transport for remote server deployments.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
GNU General Public License v3.0 (aligned with OpenProject Community Edition). |