thought-graph-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@thought-graph-mcp should our team migrate from REST to GraphQL?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ญ thought-graph-mcp
If it's hallucinating, make it think. Inspired by a research paper, this local MCP makes an LLM reason out loud as an explicit, editable graph of small thinking steps instead of one opaque answer.
Injects guidance that instructs the LLM to break a complex problem into multiple smaller reasoning paths (returned by the
begin_thinkingtool).Saves the thinking process to a Markdown file (
.md) โ every step, with dependencies, branches, confidence, and revisions.Renders an interactive HTML graph (
.html) so you can see each step as a node and how they connect.Lets you understand how the LLM reached the answer by walking the graph node-by-node (click any node for its full reasoning).
Lets you pinpoint a specific step and regenerate it โ the
revise_steptool supersedes that node, drops in a fresh revision, and tells the model which downstream steps to reconsider.
https://github.com/user-attachments/assets/29162024-35ce-4b98-8be2-9745560fe16a
Demo
Explore a full web crawler system design session
https://github.com/user-attachments/assets/b3341f27-89af-460a-927f-b4f65a39090d
Related MCP server: Sequential Thinking MCP Server
Get Started
Claude Desktop
Edit claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"thought-graph": {
"command": "npx",
"args": ["-y", "thought-graph-mcp"],
"env": {
"THOUGHT_GRAPH_DIR": "~/thought-graph-sessions"
}
}
}
}Session artifacts default to ~/thought-graph-sessions/. Override with THOUGHT_GRAPH_DIR in the server's env block if you want a different folder.
Restart Claude Desktop. Enable the server under the ๐ (MCP) menu โ the tools (begin_thinking, add_thought, etc.) become available to the model.
Claude Code
Project-scoped (create .mcp.json in your project root):
{
"mcpServers": {
"thought-graph": {
"command": "npx",
"args": ["-y", "thought-graph-mcp"]
}
}
}Or add it from the CLI:
claude mcp add thought-graph -- npx -y thought-graph-mcpVerify with claude mcp list.
Try it
In the client, ask:
Use the thought-graph tools to reason about: should our team migrate from REST to GraphQL?
The model will call begin_thinking, decompose into sub-problems, branch competing
hypotheses, attach evidence, and finalize_thinking. Open the generated .html:
Click a node โ full reasoning + its dependencies in the side panel.
Spot a weak step (e.g.
n4) โ tell the assistant "revise step n4 of session โ that assumption is wrong because โฆ". It callsrevise_step, the node is dimmed as superseded, a revision replaces it, and the graph rebuilds.
Examples
Here are a few examples of using the MCP tool to analyze mission-critical LLM inference.
Example | Problem | Nodes | Directory |
Web crawler system design + BOTE | Design a crawler for ~1B pages/month โ politeness, dedup, refresh โ with back-of-the-envelope sizing for storage, bandwidth, QPS, and fleet size | 18 | |
Rate limit service design | Design a distributed rate limiter โ high throughput, low latency, flexible per-user/key/endpoint rules, graceful degradation | 21 | |
Autocomplete feature design | Design typeahead suggestions โ data source, matching/ranking, frontend UX, latency, accessibility | 14 |
How it works
Prompt
The guidance in src/prompt.ts is injected into the context window when the tool begin_thinking is called, instructing the model to build the thought graph.
Node types
Every node in the graph has a type. It drives node color in the HTML graph, grouping in the Markdown export, and the shape of the reasoning protocol the model follows.
Type | Label | What it represents | How it's created |
| ๐ฏ Problem | The original question the session is about | Automatically by |
| ๐ฑ Decompose | A framing step that breaks the problem into axes or sub-questions |
|
| ๐งฉ Sub-problem | One focused piece of the larger problem to solve |
|
| ๐ก Hypothesis | A candidate idea or approach โ sibling hypotheses are parallel branches |
|
| ๐ Evidence | A fact, observation, or computation that supports a path |
|
| โ๏ธ Evaluation | Weighing trade-offs or checking whether a hypothesis holds |
|
| โป๏ธ Revision | A corrected replacement for an earlier step | Automatically by |
| โ Conclusion | A synthesized partial or final answer for a branch |
|
Typical flow: root โ decompose โ one or more subproblem nodes โ competing hypothesis branches on each โ evidence / evaluation attached to the relevant branch โ conclusion nodes that merge paths โ finalize_thinking for the overall answer. If a step turns out wrong, revise_step inserts a revision node and flags downstream dependents for reconsideration.
MCP Size
npx -y thought-graph-mcp downloads the npm package and its dependencies into your npm/npx cache, then runs the MCP server as a Node.js process over stdio. You do not need to clone this repo or run a bundler.
What | Approx. size | Role |
npm package ( | ~280 KB download ยท ~1.2 MB unpacked | Compiled MCP server ( |
npm dependencies (installed once, cached by npx) | ~45โ55 MB on disk | Libraries the server uses at runtime (see table below) |
Session folder (grows as you reason) | ~0.7โ1 MB per session | Self-contained graph file (embeds static CSS/JS from the package) plus ~10โ20 KB |
Total first-time footprint: roughly 50โ60 MB in npm cache. Each session .html is ~0.7โ1 MB (mostly the graph runtime block below).
What npx installs (gzip treemap)
Treemap region | bundled | share | What it is |
| 209.4 KB | 71% | Graph HTML stack: cytoscape, html2canvas, dagre, marked, dompurify, |
| 86.4 KB | 29% | MCP server process: |
Total | 295.8 KB | 100% | Minified production dependency tree (gzip); on disk |
Session artifacts on disk
After your first begin_thinking call, expect this layout:
~/thought-graph-sessions/
assets/ # static graph runtime (copied once per package version)
.asset-version
vendor/ # cytoscape, dagre, marked, html2canvas, โฆ (~1 MB)
graph/ # graph.css, graph.client.js (~22 KB)
sessions/
my-problem-abc12345.html ~0.7โ1 MB โ embeds assets (Claude in-app browser)
my-problem-abc12345.json ~10โ20 KB
my-problem-abc12345.md ~10 KBAvailable Tools
6 toolsadd_thoughtA
Record one reasoning step (a graph node). Keep it to a single idea. Use parents to link it to the node(s) it builds on โ list several to merge branches. Create sibling nodes with the same parent to explore competing paths.
Inputs: type (required), title (required), content (required), sessionId (required), +3 more.
begin_thinkingA
Start a new Thought Graph reasoning session for a complex problem. Returns a sessionId and the protocol instructions. Call this FIRST, then build the reasoning with add_thought.
Inputs: problem (required), title.
finalize_thinkingA
Record the final synthesized answer for the session and refresh the artifacts. Call after the graph supports a conclusion.
Inputs: answer (required), sessionId (required).
get_sessionA
Return the current reasoning graph as JSON (all nodes, edges, statuses) plus on-disk artifact paths. Use this to review where things stand or recover the exact graph file path.
Inputs: sessionId (required).
list_sessionsA
List existing Thought Graph sessions (id, title, step count) found on disk.
Inputs: no named parameters.
revise_stepA
Pinpoint a specific step by node id, mark it superseded, and replace it with a fresh revision node. Returns the downstream nodes you should re-examine. Use when the user points at a step or you find a flaw.
Inputs: nodeId (required), sessionId (required), newContent (required), newTitle.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 6 tools
Each tool has a clear, distinct purpose: starting a session, adding steps, revising, finalizing, and retrieving sessions. No overlap or ambiguity.
All tools use underscore_case with a verb_noun or verb_gerund pattern (e.g., add_thought, begin_thinking, list_sessions), maintaining consistency throughout.
6 tools is well-scoped for a reasoning graph system, covering core operations without unnecessary bloat.
Covers the essential lifecycle: start, add, revise, finalize, and retrieve. Missing explicit deletion of sessions or thoughts, but these are minor gaps.
Related MCP Connectors
Turn AI conversations into visual knowledge maps. Create, connect, search, and organize thoughts.
Turn grounded AI answers into trusted comparisons, plans, timelines, and decision views.
Evidence-grounded, graph-connected, correctable memory for agents.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables structured, iterative reasoning for complex problem-solving with features like confidence tracking, revision mechanisms, and branching support. Provides flexible validation and multiple output formats for systematic analysis and decision-making tasks.1184 npm72MIT
- AlicenseAqualityDmaintenanceEnables structured, step-by-step problem-solving with dynamic revision and branching capabilities. Supports breaking down complex problems into manageable steps while allowing course corrections and alternative reasoning paths.11MIT
- AlicenseBqualityNot gradedmaintenanceEnables AI assistants to perform structured, step-by-step reasoning by breaking down complex problems into numbered thoughts, with support for revising previous steps and exploring alternative reasoning paths.5-
- AlicenseAqualityCmaintenanceEnables structured step-by-step reasoning with branching, revisions, and self-critique to help break down complex problems into manageable steps with confidence tracking and thought history search.753 npm7MIT