RoadRaven — Claude Code MCP server: roadmap tree and statuses
Wires your agent into the RoadRaven desktop app so it can read the open roadmap, edit nodes and keep statuses current as work moves.
claude mcp add roadraven -- npx -y @roadraven/mcpWhat RoadRaven does
RoadRaven is a local desktop app that draws a project plan as a tree and keeps it up to date while the work happens. The MCP server hands an agent 21 tools: read the open roadmap, add a node, change it, move it, remove it, set its status. A Claude plugin adds two skills that spell out how to use those tools for planning and doing the work.
The app has to be running. Every tool reaches it over a local connection on 127.0.0.1. With the app closed you get app_not_running; with nothing open, no_file_loaded. Files are only opened or saved where you already work, so asking for another path returns path_not_permitted. The server reads a single file, event-api.json in RoadRaven's user-data folder (~/.config/RoadRaven on Linux, %LOCALAPPDATA%\RoadRaven on Windows), where the app stores its local port. Nothing goes anywhere else and no telemetry is collected.
The skills come only with the Claude plugin install. The Setup Wizard and the npx route give you the tools without them. Both skills pick up your test, lint and build commands from the project README, package manifest or CI config, so the language does not matter. The server 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.
What it helps with
- turn a request into a tree of goals, phases and tasks
- keep node statuses current while work runs
- hand a phase to a sub-agent and check the result
- record progress on a task in the node's notes
- match a change against the project's test and build commands
Example prompts for the agent
- Plan the CSV export feature as a roadmap in RoadRaven and run it phase by phase.
- Break the release into phases, write a brief for each, and run them one after another.
How to install RoadRaven
Platform CLI
claude mcp add roadraven -- npx -y @roadraven/mcpPlatform CLI
codex mcp add claude-code -- npx -y @roadraven/mcpConfig file
{
"mcpServers": {
"claude-code": {
"command": "npx",
"args": [
"-y",
"@roadraven/mcp"
]
}
}
}Config file
{
"servers": {
"claude-code": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@roadraven/mcp"
]
}
}
}Platform CLI
gemini mcp add claude-code npx -y @roadraven/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about RoadRaven
How do I install RoadRaven in Claude Code?
Through the plugin marketplace: run /plugin marketplace add Shuffzord/RoadRaven, then /plugin install roadraven@roadraven. Node.js >= 24 is required.
What does RoadRaven do?
It connects an agent to the RoadRaven desktop app: the agent reads the open roadmap, creates and edits nodes, moves them and changes their statuses. Two plugin skills describe how to plan and carry out tasks with those tools.
What has to be in place for the tools to work?
The RoadRaven app running and a roadmap open in it. Without the app the tools return app_not_running, without an open file no_file_loaded.
