# 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 install:**

   ```bash
   git clone https://gitea.kollect.biz/KollectRnD/MCP-OpenProject.git
   cd MCP-OpenProject
   pnpm install
   ```

2. **Configure environment:**

   ```bash
   cp .env.example .env
   ```

   Edit `.env` with your OpenProject URL and API key:

   ```
   OPENPROJECT_URL=https://your-instance.openproject.com
   OPENPROJECT_API_KEY=your-api-key-here
   ```

3. **Build:**

   ```bash
   pnpm 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
pnpm dev
```

## 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