152 lines
4.0 KiB
Markdown
152 lines
4.0 KiB
Markdown
# OpenProject MCP Server
|
|
|
|
A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects AI assistants to [OpenProject](https://www.openproject.org/) via the v3 REST API.
|
|
|
|
## Features
|
|
|
|
- 18 MCP tools covering projects, work packages, relations, users, time tracking, versions, and activities
|
|
- Stdio transport — works with Claude Code, Zed, Claude Desktop, and any MCP-compatible client
|
|
- HAL+JSON responses formatted into readable text summaries
|
|
- Optimistic concurrency control for work package updates
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+
|
|
- pnpm
|
|
- An OpenProject instance with an API key
|
|
|
|
## Setup
|
|
|
|
1. **Clone and bootstrap:**
|
|
|
|
```bash
|
|
git clone https://gitea.kollect.biz/KollectRnD/MCP-OpenProject.git
|
|
cd MCP-OpenProject
|
|
just bootstrap # installs uv, just, commitizen, pre-commit, git hooks
|
|
just install # pnpm install
|
|
```
|
|
|
|
2. **Configure environment:**
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
cp .mcp.json.example .mcp.json
|
|
```
|
|
|
|
Edit `.env` with your OpenProject URL and API key:
|
|
|
|
```
|
|
OPENPROJECT_URL=https://your-instance.openproject.com
|
|
OPENPROJECT_API_KEY=your-api-key-here
|
|
```
|
|
|
|
Edit `.mcp.json` and replace `<YOUR_API_KEY_HERE>` with your key.
|
|
|
|
> **Note:** `.env` and `.mcp.json` are gitignored — secrets stay local.
|
|
|
|
3. **Build:**
|
|
|
|
```bash
|
|
just build
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Claude Code
|
|
|
|
Add to your project's `.mcp.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"openproject": {
|
|
"command": "node",
|
|
"args": ["dist/index.js"],
|
|
"env": {
|
|
"OPENPROJECT_URL": "https://your-instance.openproject.com",
|
|
"OPENPROJECT_API_KEY": "<YOUR_API_KEY>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Claude Desktop
|
|
|
|
Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"openproject": {
|
|
"command": "node",
|
|
"args": ["/absolute/path/to/MCP-OpenProject/dist/index.js"],
|
|
"env": {
|
|
"OPENPROJECT_URL": "https://your-instance.openproject.com",
|
|
"OPENPROJECT_API_KEY": "<YOUR_API_KEY>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Development
|
|
|
|
Run directly without building:
|
|
|
|
```bash
|
|
just dev
|
|
```
|
|
|
|
### Just Commands
|
|
|
|
```bash
|
|
just install # Install dependencies
|
|
just build # Compile TypeScript
|
|
just dev # Run with tsx (no build)
|
|
just start # Run compiled server
|
|
just bootstrap # Full setup (first time)
|
|
just setup # Install commitizen + pre-commit
|
|
just update # Update pre-commit hooks
|
|
just changelog # Generate CHANGELOG.md
|
|
just bump # Bump version (SemVer)
|
|
```
|
|
|
|
## Available Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `list_projects` | List all accessible projects |
|
|
| `get_project` | Get project details by ID or identifier |
|
|
| `list_work_packages` | List work packages with filtering |
|
|
| `get_work_package` | Get work package details |
|
|
| `create_work_package` | Create a new work package |
|
|
| `update_work_package` | Update an existing work package |
|
|
| `add_work_package_comment` | Add a comment to a work package |
|
|
| `list_relations` | List relations for a work package |
|
|
| `create_relation` | Create a relation between work packages |
|
|
| `delete_relation` | Delete a relation |
|
|
| `list_statuses` | List available statuses |
|
|
| `list_types` | List available types (Task, Bug, Feature, etc.) |
|
|
| `list_priorities` | List available priorities |
|
|
| `get_me` | Get authenticated user profile |
|
|
| `list_users` | List all users |
|
|
| `list_time_entries` | List time entries |
|
|
| `log_time` | Log time on a work package |
|
|
| `list_versions` | List project versions/milestones |
|
|
| `list_work_package_activities` | List work package activity history |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
index.ts — Entry point, server bootstrap, tool registration
|
|
client.ts — OpenProject API v3 HTTP client
|
|
tools.ts — MCP tool definitions with Zod schemas
|
|
handlers.ts — Tool handlers (API calls + response formatting)
|
|
```
|
|
|
|
## License
|
|
|
|
Private — Kollect Systems
|