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

1. Injects guidance that instructs the LLM to break a complex problem into multiple smaller reasoning paths (returned by the begin_thinking tool).

2. Saves the thinking process to a Markdown file (.md) — every step, with dependencies, branches, confidence, and revisions.

3. Renders an interactive HTML graph (.html) so you can see each step as a node and how they connect.

4. Lets you understand how the LLM reached the answer by walking the graph node-by-node (click any node for its full reasoning).

5. Lets you pinpoint a specific step and regenerate it — the revise_step tool 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.json

• Windows: %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-mcp

Verify 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 calls revise_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.

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.

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.

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)

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 KB