# OpenProject MCP Server

Model Context Protocol (MCP) server for OpenProject API integration. Enables AI assistants to interact with OpenProject work packages, projects, and time tracking.

## Installation

### Global Installation (Recommended)

```bash
npm install -g openproject-mcp
```

### Local Installation

```bash
npm install openproject-mcp
```

## Configuration

### Get OpenProject API Key

1. Log into your OpenProject instance
2. Go to **My Account** → **Access tokens**
3. Create a new API token
4. Copy the token

### Add to Kiro MCP Config

Add to `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "openproject": {
      "command": "npx",
      "args": ["-y", "openproject-mcp"],
      "env": {
        "OPENPROJECT_URL": "https://your-openproject-instance.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "openproject": {
      "command": "openproject-mcp",
      "env": {
        "OPENPROJECT_URL": "https://your-openproject-instance.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects |
| `get_work_package` | Get work package details by ID |
| `list_work_packages` | List work packages with filters |
| `get_children` | Get child work packages of a parent |
| `list_statuses` | List all available statuses |
| `list_types` | List all work package types (Feature, Task, Bug, etc.) |
| `get_user` | Get user information |
| `create_work_package` | Create a new work package |
| `update_work_package` | Update an existing work package |
| `log_time` | Log time entry for a work package |
| `raw_api_call` | Make a raw API call to any endpoint |

## Usage Examples

### List Children of a Feature

```javascript
get_children({ parentId: 211 })
```

### Create a New Task

```javascript
create_work_package({
  subject: "Implement token budget management",
  parentId: 538,
  assigneeId: 10,
  startDate: "2026-01-15",
  dueDate: "2026-01-15"
})
```

### List Tasks Assigned to Me

```javascript
list_work_packages({ assigneeId: "me" })
```

### Update Work Package Status

```javascript
update_work_package({
  id: 123,
  statusId: 12,  // Status ID from list_statuses
  estimatedTime: "PT2H"  // 2 hours in ISO 8601 format
})
```

### Log Time

```javascript
log_time({
  workPackageId: 123,
  hours: 2.5,
  comment: "Implemented feature X",
  spentOn: "2026-01-23"
})
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENPROJECT_URL` | Yes | Your OpenProject instance URL |
| `OPENPROJECT_API_KEY` | Yes | API key from OpenProject |

## Requirements

- Node.js >= 18.0.0
- OpenProject instance with API access

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Links

- [OpenProject API Documentation](https://www.openproject.org/docs/api/)
- [Model Context Protocol](https://modelcontextprotocol.io/)