RoadRaven

What the RoadRaven MCP server does

The RoadRaven MCP server gives an MCP host access to a roadmap open in the RoadRaven desktop application. The roadmap is represented as a tree and stored as plain roadmap.json data in the project repository. Agents can use the server to create and modify nodes, organize the hierarchy, and update progress as work proceeds.

RoadRaven is intended for local project planning rather than a hosted project-management service. The application binds to 127.0.0.1, does not require an account, and can work without an internet connection after installation. Other processes can also report progress through the app's local Event API, including scripts, CI jobs, and agent workflows that can open a WebSocket.

How the RoadRaven MCP server works

The desktop application must be running before MCP calls are made. The server sends requests to the application's local Event API; if the application is closed, calls return app_not_running rather than operating on the roadmap independently.

An MCP host starts the server as a local process, commonly through the npm package @roadraven/mcp. The app and server use the roadmap file in the repository, while the desktop UI renders the tree and shows changes as they arrive. The application supports agent-safe writes, including optimistic locking and batch updates.

The roadmap schema leaves statuses, node types, and hierarchy choices to the user. This makes the server suitable for workflows that define their own planning conventions, but it also means the agent or surrounding workflow must decide how those fields are used.

Setup and configuration

Install RoadRaven from GitHub Releases on Windows x64 or Linux x86_64, then launch the desktop application. Windows uses the system WebView2 runtime; the Linux package includes Chromium through CEF. macOS is listed as a future installer target in the supplied project status.

The Setup Wizard can detect Claude Code and OpenCode and register the bundled MCP server. For another MCP host, Node.js version 24 or newer is required. A typical registration command is:

claude mcp add -s user roadraven -- npx -y @roadraven/mcp@0.9.0

Use a package version that matches the installed desktop app. The application warns when versions differ. The init command can add RoadRaven guidance to a CLAUDE.md file so Claude knows to use the roadmap, but the MCP tools themselves do not require that initialization step.

The Claude Code plugin is an alternative setup route. It requires Node.js 24 or newer and also supplies the orchestrate and work-node skills, along with the RoadRaven HUD mod.

Tools and capabilities

The RoadRaven MCP server exposes 21 tools covering roadmap editing and progress reporting. Supported operations include:

• Creating roadmap tree nodes.
• Editing node content and metadata.
• Moving nodes within the hierarchy.
• Deleting nodes.
• Updating node statuses as work changes.
• Applying batch updates through the app's agent-safe write path.

The desktop app provides the visual side of the workflow: a tree canvas, keyboard editing, markdown notes, metadata, an outline navigator, and a live event log. The MCP server is therefore most useful when an agent needs to change the plan while a developer supervises those changes in the application.

Limitations and notes

RoadRaven is alpha software at version 0.9.0. Its data format, APIs, and packaging may change before version 1.0. The desktop app is required for every MCP operation, so this is not a standalone roadmap service or a remote API.

The current installers target Windows and Linux. Windows releases are unsigned and may trigger SmartScreen. The server and app are designed for local use, and the supplied material describes binding to 127.0.0.1; it does not describe remote-host access.

The README mentions installation guidance for Cursor, Codex, Copilot, Gemini, and OpenCode, but the available client identifiers do not include all of those products. A custom producer can use the Event API, although the project notes that the @roadraven/core package is not yet available on npm and may need to be built from source.