# OpenProject MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to an OpenProject instance. It lets Claude query, search, and manage projects, work packages, users, and time entries through natural language.

## Features

- List and filter projects
- List, search, and inspect work packages (tasks, bugs, features, epics, user stories)
- View work package activity history
- List and inspect users
- List and inspect time entries
- Create work packages individually or in bulk, with parent/child nesting (e.g. user stories under an epic)
- Paginated results for large datasets

## Prerequisites

- Node.js 18+ or Bun 1.0+
- An OpenProject 13+ instance with API access
- An OpenProject API token (Administration → API & Webhooks → Personal Access Tokens)

## Installation

```bash
git clone <repo-url>
cd openproject-mcp-server
npm install
cp .env.example .env
```

Edit `.env`:

```env
OPENPROJECT_URL=https://your-openproject-instance.example.com
OPENPROJECT_API_TOKEN=your-api-token
OPENPROJECT_PAGE_SIZE=50
```

Required token permissions: `view_work_packages`, `view_projects`, `view_users`, `view_time_entries`, and `edit_work_packages` if you want Claude to create work packages.

Build:

```bash
npm run build
```

## Usage

### Claude Code

Add the server under Settings → MCP Servers → Add Local Server:

- **Command**: `node`
- **Arguments**: `["path/to/openproject-mcp-server/dist/index.js"]`
- **Environment Variables**: the values from your `.env`

### Local testing

```bash
npm run dev
npm run inspect
```

`inspect` opens the MCP Inspector web UI to try each tool directly.

## Available tools

### Projects
- `list_projects` — list projects, optionally filtered by name and status
- `get_project` — get details of a specific project

### Work packages
- `list_work_packages` — list with filtering by project, status, priority, assignee, or search text
- `get_work_package` — get full details of a work package
- `get_work_package_activities` — get change/comment history
- `search_work_packages` — full-text search

### Users
- `list_users` — list all users
- `get_user` — get details of a specific user

### Time entries
- `list_time_entries` — list with filtering by project, user, work package, and date range
- `get_time_entry` — get details of a specific time entry

### Creating work packages
- `list_project_types` — list available work package types (Epic, User Story, Task, Bug...) and their IDs; call this first, type IDs vary between instances
- `create_work_package` — create one work package; use `parent_id` to nest under an epic
- `create_work_packages_bulk` — create up to 100 work packages in one call, each with its own `parent_id`; returns a per-item success/failure report

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── client/
│   └── openproject.ts    # HTTP client for the OpenProject API
├── tools.ts               # Tool registration and handlers
├── schemas/
│   └── index.ts           # Zod input validation
└── utils/
    └── formatters.ts       # Markdown output formatting
```

## Security

- Bearer token authentication, no credentials in plain requests
- Input validation with Zod
- `.env` holds the token locally and is git-ignored — never commit it

## Troubleshooting

- **Authentication failed**: check the token in `.env` is valid, regenerate if needed
- **Connection error**: verify `OPENPROJECT_URL` is reachable from your machine
- **No projects found**: verify your token's user has permission to view projects

## License

MIT