open-project-sidecar-mcp (1.5.0-alpha)
Installation
registry=npm install open-project-sidecar-mcp@1.5.0-alpha"open-project-sidecar-mcp": "1.5.0-alpha"About this package
open-project-mcp
MCP server for OpenProject project management. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible client.
Provides 57 tools for managing projects, work packages, versions, time tracking, wiki pages, boards, news, forums, and more -- all through the Model Context Protocol.
Why this package?
Existing OpenProject MCP servers (openproject-mcp, openproject-mcp-server) cover basic CRUD for projects, work packages, and time tracking -- roughly 8-27 tools depending on the package. This server goes further with 57 tools, adding coverage for areas the others don't touch:
- Wiki pages -- create, read, update, and delete project documentation
- Boards -- create Kanban boards (status, assignee, version, or free-form layouts)
- Saved queries -- manage filtered work package views with custom columns and sorting
- News and release notes -- publish project updates and auto-generate changelogs from version data
- Forums -- create discussion boards, post topics, and manage threads
- Sprint overview -- get structured breakdowns of version progress with work package counts
- Work package relations -- manage blocks, follows, relates, and other dependency links
- Comments and activity -- read activity history and post comments on work packages
- Project memberships -- add/remove users and manage role assignments
- Notifications -- list and manage in-app notifications
- Commit message formatting -- generate conventional commits with OpenProject references
What this is (and isn't)
This is an MCP server -- it exposes 57 tools that any MCP-compatible AI client can call, but it does not include agent skills, prompt templates, or workflow automation. It is a bridge between your AI coding tool and your OpenProject instance.
Tested with Claude Code. Other MCP clients (Cursor, Windsurf, etc.) should work since the server follows the MCP specification, but they are not actively tested. Bug reports and contributions for other clients are welcome.
Agent skills are separate. If you want guided workflows (e.g., "work on ticket #123" with automatic branching and commit conventions), those are configured as client-side skills in your AI tool, not part of this server.
Quick start
npx -y open-project-sidecar-mcp --setup
The --setup flag launches an interactive wizard that walks you through deployment mode selection, credentials, Docker compose scaffolding (sidecar mode), connectivity testing, and client registration.
Without --setup, the server starts normally and loads .env from your current working directory automatically.
Re-running --setup is safe on existing installations -- it detects your existing setup, reuses API keys, and cleans up stale registrations.
Deployment modes
| Direct (stdio) | Docker sidecar | |
|---|---|---|
| Best for | Any developer, solo or team | admin_command, persistent server |
| Transport | stdio (default) | HTTP (always enabled) |
| Requires | Node 18+ | Docker, Docker Compose |
| API tools (56) | All | All |
admin_command |
No | Yes |
Direct mode: Your AI client launches the MCP server as a child process. Run the setup wizard, and you're done.
Docker sidecar: Persistent container with HTTP transport. Provides admin_command for Rails console operations (module management, custom types/statuses, custom fields, backlogs). Team members connect by URL without needing Node.js locally.
See wiki-drafts/03-deployment-modes.md for detailed setup instructions, compose examples, manual configuration, and connecting team members.
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
OPENPROJECT_URL |
Yes | -- | Base URL of your OpenProject instance |
OPENPROJECT_API_KEY |
Yes | -- | API key (create one in OpenProject > My Account > Access Tokens) |
OPENPROJECT_CONTAINER |
Docker sidecar | openproject-openproject-1 |
Docker container name for admin_command |
OPENPROJECT_COMPOSE_FILE |
No | -- | Path to docker-compose.yml (alternative to container name) |
MCP_TRANSPORT |
Docker sidecar | stdio |
Set to http for Docker sidecar (always enabled) |
MCP_PORT |
No | 3000 |
HTTP server port (Docker sidecar only) |
MCP_API_KEY |
Docker sidecar | -- | Bearer token for HTTP auth (Docker sidecar only) |
The server looks for .env in: (1) current working directory, (2) package directory. First file found wins. Existing environment variables are never overwritten.
Available tools
57 tools across 16 categories. All work in every deployment mode unless noted.
| Category | Tools | Highlights |
|---|---|---|
| Projects | 4 | list, get, create, update |
| Work packages | 4 | list (with filters/sorting/pagination), get, create, update |
| Relations | 3 | list, create, delete (blocks, follows, relates, etc.) |
| Comments & activity | 3 | list activity history, add/update comments |
| Lookups | 4 | statuses, types, priorities, users |
| Versions & sprints | 5 | CRUD + sprint overview with breakdowns |
| Time tracking | 2 | log time, list entries |
| Wiki (sidecar only) | 5 | CRUD + list (requires wiki module) |
| Queries | 4 | CRUD for saved filtered views |
| Boards (sidecar only) | 3 | list, create, delete (status/assignee/version layouts) |
| News | 5 | CRUD + auto-generate release notes from versions |
| Forums (sidecar only) | 5 | CRUD for forums and messages/topics |
| Memberships | 5 | list, add, update, remove members + list roles |
| Notifications | 3 | list, mark read, mark all read |
| Admin (sidecar only) | 1 | Rails console: modules, types, statuses, custom fields |
| Utilities | 1 | conventional commit message formatting |
See wiki-drafts/06-tool-reference.md for the full tool reference with descriptions.
Troubleshooting
Most issues are fixed by re-running the setup wizard:
npx -y open-project-sidecar-mcp --setup
| Problem | Cause | Fix |
|---|---|---|
OPENPROJECT_URL is required |
.env file missing or not found |
Run --setup for guided setup |
Connection refused |
Server not running or wrong port | Check server is running and MCP_PORT matches client config |
401 Unauthorized |
Key mismatch between client/server | Re-run --setup to sync keys |
| Tools not appearing in Claude Code | Stale or project-scoped config | Re-run --setup to clean old entries and register globally |
admin_command fails |
Docker socket not mounted | Add /var/run/docker.sock:/var/run/docker.sock to compose volumes |
See wiki-drafts/08-troubleshooting.md for diagnostic commands and additional issues.
Development
npm install # Install dependencies
npm test # Run tests
npm run lint # Lint (uses Biome)
npm run audit # Check for vulnerable dependencies
All tools are defined in index.js using the MCP SDK's server.tool() method. Each tool specifies its name, description, Zod schema for parameters, and handler function. Pure helper functions are exported and tested in test.js.
License
MIT
Dependencies
Dependencies
| ID | Version |
|---|---|
| @modelcontextprotocol/sdk | ^1.12.0 |
| zod | ^3.23.0 |
Development dependencies
| ID | Version |
|---|---|
| @biomejs/biome | ^1.9.0 |