mcp-roadmapsh
MCP server for roadmap.sh — developer roadmaps, best
practices, interview questions, project ideas, videos, and local progress
tracking. Built on the official @modelcontextprotocol/sdk (TypeScript / stdio).
All data comes from official, public sources — no scraping, no mock data:
https://roadmap.sh/{slug}.json— rendered roadmap graphsraw.githubusercontent.com/nilbuild/developer-roadmap— topic markdown- GitHub contents API — dynamic slug listings
Prerequisite
Node.js 20 or newer (node --version to check). That is
the only requirement — npx (bundled with Node) handles the rest, no manual
clone or build needed.
Quick start
Claude Code (one command)
# Once published to npm:
claude mcp add roadmapsh -- npx -y mcp-roadmapsh
# Works today, straight from GitHub (npx builds it for you):
claude mcp add roadmapsh -- npx -y github:aissablk1/mcp-roadmapsh
Any MCP client (JSON config)
{
"mcpServers": {
"roadmapsh": { "command": "npx", "args": ["-y", "mcp-roadmapsh"] }
}
}
Replace mcp-roadmapsh with github:aissablk1/mcp-roadmapsh to run the latest
GitHub version before the npm release.
From source (contributors)
git clone https://github.com/aissablk1/mcp-roadmapsh.git
cd mcp-roadmapsh
npm install # `prepare` builds dist/ automatically
npm test # end-to-end test against real data
node dist/index.js # stdio MCP server
npm run inspect # open the MCP Inspector
Tools
| Tool | Purpose |
|---|---|
roadmap_diagnose | Connectivity + cache/state status |
roadmap_list | List all roadmap slugs |
roadmap_get | Roadmap graph by slug (outline or raw) |
roadmap_topic | Topic markdown + links (by nodeId or query) |
roadmap_export | Export a whole roadmap as markdown/text |
roadmap_search | Search slugs by keyword within a scope |
best_practices_list / best_practices_get | Best-practice guides |
questions_list / questions_get | Interview question groups |
projects_list / project_get | Practice project ideas |
videos_list | Video resources |
progress_mark | Mark a topic learning / done / skip (local) |
progress_status | Completion percent for a roadmap |
progress_next | Recommend the next topic to learn |
Configuration (env)
| Variable | Default | Purpose |
|---|---|---|
ROADMAPSH_CACHE_DIR | ~/.cache/mcp-roadmapsh | HTTP cache directory |
ROADMAPSH_CACHE_TTL_MS | 86400000 (24 h) | Cache TTL |
ROADMAPSH_STATE_DIR | ~/.local/state/mcp-roadmapsh | Progress state |
ROADMAPSH_TIMEOUT_MS | 20000 | HTTP timeout |
ROADMAPSH_OWNER | nilbuild | GitHub owner of the developer-roadmap repo |
ROADMAPSH_BRANCH | master | developer-roadmap branch |
GITHUB_TOKEN | — | Optional, raises GitHub API rate limit |
Publishing (maintainers)
npm publish # to npmjs.com (npm login required first)
npx -y @modelcontextprotocol/publisher publish # to the official MCP registry (server.json)
The package ships mcpName and a server.json so it can be listed in the
official Model Context Protocol registry.
License
MIT — Aïssa BELKOUSSA