Summary
Connects Claude to roadmap.sh's public JSON APIs and the developer-roadmap GitHub repo to pull learning paths, best practices, interview questions, and project ideas. You get tools to list roadmaps, fetch topic markdown by node ID or search query, export entire roadmaps as text, and track progress locally in your state directory. The server caches HTTP responses for 24 hours by default and supports all the main content types: roadmaps, best practices, questions, projects, and videos. Useful when you want Claude to guide you through a learning path, suggest next topics based on your progress, or pull reference material without leaving the chat. Runs via npx with zero setup beyond Node 20+.
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →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
Featured
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →