mcpField
R
RoadRaven

RoadRaven

Local
shuffzord.github.ioProductivity9Updated 2d ago
RepositoryVisit website

About RoadRaven

RoadRaven’s MCP server connects Claude Code and other MCP hosts to the running RoadRaven desktop app, where agents can manage a project roadmap. It provides 21 tools and a Claude Code plugin with two workflow skills.

Key features

  1. 01Read the open roadmap
  2. 02Create, edit, move, and delete nodes
  3. 03Set roadmap node statuses
  4. 04Two Claude Code workflow skills

Use cases

  1. 01Turn a request into a phased roadmap
  2. 02Carry out a roadmap task and update its status

MCP support

The local stdio MCP server exposes 21 tools for reading and editing the roadmap in the running RoadRaven app. It connects over WebSocket on 127.0.0.1.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "shuffzord-roadraven": {
      "command": "npx",
      "args": [
        "-y",
        "@roadraven/mcp"
      ]
    }
  }
}
Run commandnpx -y @roadraven/mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@roadraven/mcp0.9.2

Tools

21

Saved tool list · updated 2d ago

ParameterTypeRequiredDescription
metaobjectNoArbitrary key-value metadata, e.g. { branch, commit, ci_run_id }
nodeIdstringYesThe node UUID from the roadmap
statusenumYesCore node statusnot-started | in-progress | completed | blocked
expectedRevisionintegerNoRevision from your last getRoadmap/getNode read. If the roadmap changed since, the write fails with stale_write instead of clobbering.

Details

From the project README

@roadraven/mcp — RoadRaven for Claude Code

The MCP server and Claude Code plugin for RoadRaven, a local desktop app that shows your project's plan as a tree and updates it live as the work happens. The server gives an agent 21 tools to read the open roadmap, create, edit, move and delete nodes, and set their status. The plugin adds two skills that tell Claude how to use those tools to plan and run real work.

Source-available, FSL-1.1-MIT.

The app must be running

Every tool talks to the RoadRaven desktop app over a local connection on 127.0.0.1. With the app closed, tools return app_not_running; with no roadmap open, no_file_loaded. The app only opens or saves files where you already work, so a request for another path returns path_not_permitted. Install the app first: see Install.

What it does on your machine

  • Downloads and runs @roadraven/mcp from npm through npx, pinned to the plugin's exact version, as a local stdio MCP server.
  • Reads one file: event-api.json in RoadRaven's user-data folder (~/.config/RoadRaven on Linux, %LOCALAPPDATA%\RoadRaven on Windows), which the desktop app writes with its local port.
  • Connects only to the RoadRaven desktop app, over a WebSocket on 127.0.0.1, to read and edit the open roadmap. It sends nothing anywhere else and collects no telemetry.
  • Writes files only when you run npx @roadraven/mcp init yourself: it offers to add a short RoadRaven section to a CLAUDE.md, and asks first.
  • The skills are instructions for Claude; they run nothing on their own.

Install

Three ways, easiest first.

Setup Wizard. Launch RoadRaven. The first-run Setup Wizard detects Claude Code and OpenCode and registers this server with one click. Re-open it from the ⚙ button in the top bar. If the Claude Code plugin below is already installed, the wizard defers to it.

Claude Code plugin. Requires Node.js >= 24. From inside Claude Code:

/plugin marketplace add Shuffzord/RoadRaven
/plugin install roadraven@roadraven

Any other MCP host. Requires Node.js >= 24. Pin the version that matches your installed app (the app warns on a major.minor mismatch):

claude mcp add -s user roadraven -- npx -y @roadraven/[email protected]

To add a short RoadRaven section to a CLAUDE.md (it asks whether to use the current project or ~/.claude/CLAUDE.md), run npx -y @roadraven/[email protected] init.

Skills

The skills ship with the Claude Code plugin install only. The Setup Wizard and npx paths give you the tools without them.

roadraven:orchestrate turns a request into a roadmap tree (goal, phases, tasks), writes a brief per phase, hands each phase to a sub-agent, re-runs your project's own checks to verify the result, and keeps node status current while you watch.

Plan the CSV export feature as a roadmap in RoadRaven and run it phase by phase.

roadraven:work-node is how one task gets done: claim a node, set it in progress, checkpoint into its notes, touch only the files the brief names, prove a fix with a failing test first, run the checks, report, set the final status.

Pick up the first not-started node in the open roadmap, do the work, and keep its status current.

Both skills find your project's test, lint and build commands from its README, package manifest or CI config, so they work in any language. If the app is not running they ask you once to start it, then fall back to a markdown worklog and say so.

More: MCP install guide, plugin authoring guide.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.