open-project-mcp

MCP server for OpenProject project management. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible client.

Provides 62 tools for managing projects, work packages, versions, time tracking, wiki pages, boards, news, forums, and more -- all through the Model Context Protocol.

Roadmap and issue tracking

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 62 tools, adding coverage for areas the others don't touch:

• Wiki pages -- create, read, update, and delete project documentation
• Boards -- create and manage Kanban boards (status, assignee, subtasks, or free-form layouts)
• Watchers -- manage notification subscriptions on work packages
• Delete operations -- delete work packages and projects
• 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 62 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.

Updating

Direct (stdio):

npx -y open-project-sidecar-mcp@latest --setup

Specifying @latest (or a specific version like @1.7.0) ensures npx fetches the new version instead of using its cache. Re-running --setup is optional but recommended -- it picks up any config changes and re-registers the server.

Docker sidecar:

docker compose pull mcp && docker compose up -d mcp

This pulls the latest image and restarts the container. No config changes needed between versions. To pin a specific version, set image: git.bros.ninja/mike/open-project-sidecar-mcp:1.7.0 in your compose file.

Check your version: npx open-project-sidecar-mcp --version (direct) or curl http://localhost:3000/health (sidecar).

See wiki-drafts/09-updating.md for the full update guide.

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 (61) | 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

62 tools across 16 categories. All work in every deployment mode unless noted.

| Category | Tools | Highlights | | --------------------- | ----- | ------------------------------------------------------------------- | | Projects | 5 | list, get, create, update, delete | | Work packages | 5 | list (with filters/sorting/pagination), get, create, update, delete | | Relations | 3 | list, create, delete (blocks, follows, relates, etc.) | | Comments & activity | 3 | list activity history, add/update comments | | Watchers | 3 | list, add, remove watchers on work packages | | 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 | 3 | list, create, delete (status/assignee/subtasks 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