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

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.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)

Terminal

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