Mcp Roadmapsh

io.github.aissablk1Published by GitHub account aissablk1v0.2.0Updated Nov 3, 2026

MCP server for roadmap.sh: roadmaps, best practices, interview questions, projects & progress

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local MCP server that gives an assistant roadmap.sh developer roadmaps, best practices, interview questions, project ideas and local learning progress.

What you can do
  • List and search roadmap slugs, and fetch a roadmap graph as outline or raw data
  • Read topic markdown and links by node ID or query, and export a whole roadmap as markdown or text
  • Browse best-practice guides, interview question groups, practice project ideas and video resources
  • Mark topics as learning, done or skipped locally, check completion percentage and get the next recommended topic
  • Run a diagnostic check of connectivity and cache/state status
When to use it
Useful when you want an assistant to guide developer learning along roadmap.sh paths: exploring a roadmap, pulling topic notes, quizzing with interview questions, picking practice projects, or tracking which topics are finished.
Requirements
Runs as a local process via npx, so Node.js 20 or newer is required. Network access to roadmap.sh and GitHub is needed. Optional environment variables set cache and state directories, cache TTL, HTTP timeout, GitHub owner and branch, and GITHUB_TOKEN to raise GitHub API rate limits.
Before you install
Progress is stored locally in a state directory, and roadmap and topic data are fetched from roadmap.sh and GitHub, so those requests leave the machine. GITHUB_TOKEN is optional but is a credential; only set it if you accept it being used for GitHub API calls. Progress marking only changes local state, not any remote account.

Installation

In SourceWeft

  1. Open Mcp Roadmapsh in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-roadmapsh

[npm] [Node] [License: MIT]

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 graphs
  • raw.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)

bash
# 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)

json
{  "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)

bash
git clone https://github.com/aissablk1/mcp-roadmapsh.gitcd mcp-roadmapshnpm install        # `prepare` builds dist/ automaticallynpm test           # end-to-end test against real datanode dist/index.js # stdio MCP servernpm run inspect    # open the MCP Inspector

Tools

ToolPurpose
roadmap_diagnoseConnectivity + cache/state status
roadmap_listList all roadmap slugs
roadmap_getRoadmap graph by slug (outline or raw)
roadmap_topicTopic markdown + links (by nodeId or query)
roadmap_exportExport a whole roadmap as markdown/text
roadmap_searchSearch slugs by keyword within a scope
best_practices_list / best_practices_getBest-practice guides
questions_list / questions_getInterview question groups
projects_list / project_getPractice project ideas
videos_listVideo resources
progress_markMark a topic learning / done / skip (local)
progress_statusCompletion percent for a roadmap
progress_nextRecommend the next topic to learn

Configuration (env)

VariableDefaultPurpose
ROADMAPSH_CACHE_DIR~/.cache/mcp-roadmapshHTTP cache directory
ROADMAPSH_CACHE_TTL_MS86400000 (24 h)Cache TTL
ROADMAPSH_STATE_DIR~/.local/state/mcp-roadmapshProgress state
ROADMAPSH_TIMEOUT_MS20000HTTP timeout
ROADMAPSH_OWNERnilbuildGitHub owner of the developer-roadmap repo
ROADMAPSH_BRANCHmasterdeveloper-roadmap branch
GITHUB_TOKEN—Optional, raises GitHub API rate limit

Publishing (maintainers)

bash
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

Source: README.md at commit a41a2d5

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts